* [PATCH v3 1/3] doc: introduce a synopsis custom paragraph attribute
2024-08-11 15:20 ` [PATCH v3 " Jean-Noël Avila via GitGitGadget
@ 2024-08-11 15:20 ` Jean-Noël Avila via GitGitGadget
2024-08-11 15:20 ` [PATCH v3 2/3] doc: update the guidelines to reflect the current formatting rules Jean-Noël Avila via GitGitGadget
` (3 subsequent siblings)
4 siblings, 0 replies; 45+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2024-08-11 15:20 UTC (permalink / raw)
To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
In order to follow the common manpage usage, the synopsis of the
commands needs to be heavily typeset. A first try was performed with
using native markup, but it turned out to make the document source
almost unreadable, difficult to write and prone to mistakes with
unwanted Asciidoc's role attributes.
In order to both simplify the writer's task and obtain a consistant
typesetting in the synopsis, a custom 'synopsis' paragraph type is
created and the backends of asciidoc and asciidoctor take in charge to
correctly add the required typesetting.
additionally, a 's' macro ('s' standing for synopsis) is introduced to
allow writers to freely apply automatic styling whereever required.
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/asciidoc.conf | 21 +++++++++++++++-
Documentation/asciidoctor-extensions.rb | 33 +++++++++++++++++++++++++
t/t0450-txt-doc-vs-help.sh | 11 +++------
3 files changed, 57 insertions(+), 8 deletions(-)
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 60f76f43eda..04405453415 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -9,7 +9,7 @@
[macros]
(?su)[\\]?(?P<name>linkgit):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
-
+(?su)[\\]?(?P<name>s):(?P<target>\S*?)\["(?P<attrlist>.*?)"\]=
[attributes]
asterisk=*
plus=+
@@ -28,6 +28,9 @@ ifdef::backend-docbook[]
{0#<citerefentry>}
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
{0#</citerefentry>}
+
+[s-inlinemacro]
+{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<emphasis>\1</emphasis>', re.sub(r'([\[ |()>]|^|\]|>)(\.?[-a-zA-Z0-9:+=~@,\/]+\.?)',r'\1<literal>\2</literal>', '{attrlist}'))}
endif::backend-docbook[]
ifdef::backend-docbook[]
@@ -56,4 +59,20 @@ ifdef::backend-xhtml11[]
git-relative-html-prefix=
[linkgit-inlinemacro]
<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
+
+[s-inlinemacro]
+{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<em>\1</em>', re.sub(r'([\[ |()>]|^|\]|>)(\.?[-=a-zA-Z0-9:+,@]+\.?)',r'\1<code>\2</code>', '{attrlist}'))}
+
+endif::backend-xhtml11[]
+
+ifdef::backend-docbook[]
+ifdef::doctype-manpage[]
+[paradef-default]
+synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@]+\.?+)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]+>!<emphasis>\\0</emphasis>!g'"
+endif::doctype-manpage[]
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[paradef-default]
+synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@]+\.?)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]+>!<em>\\0</em>!g'"
endif::backend-xhtml11[]
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index d906a008039..46cbbbbfd76 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -24,6 +24,21 @@ module Git
end
end
+ class SynopsisMacroProcessor < Asciidoctor::Extensions::InlineMacroProcessor
+ use_dsl
+
+ named :s
+ match(/s:\["(.+?)"\]/)
+
+ def process(parent, target, attrs)
+ l = target.gsub(/([\[\] |()]|^|>)(\.?[-a-zA-Z0-9:+=~@,\/]+\.?)/, '\1{empty}`\2`{empty}')
+ .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
+ .gsub(']', ']{empty}')
+
+ create_inline parent, :quoted, l, attributes: { 'subs' => :normal }
+ end
+ end
+
class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor
def process document, output
if document.basebackend? 'docbook'
@@ -39,10 +54,28 @@ module Git
output
end
end
+
+ class SynopsisBlock < Asciidoctor::Extensions::BlockProcessor
+
+ use_dsl
+ named :synopsis
+ parse_content_as :simple
+
+ def process parent, reader, attrs
+ outlines = reader.lines.map do |l|
+ l.gsub(/([\[\] |()>]|^)([-a-zA-Z0-9:+=]+)/, '\1{empty}`\2`{empty}')
+ .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
+ .gsub(']', ']{empty}')
+ end
+ create_block parent, :verse, outlines, attrs
+ end
+ end
end
end
Asciidoctor::Extensions.register do
inline_macro Git::Documentation::LinkGitProcessor, :linkgit
+ inline_macro Git::Documentation::SynopsisMacroProcessor
+ block Git::Documentation::SynopsisBlock
postprocessor Git::Documentation::DocumentPostProcessor
end
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index 69917d7b845..f99a69ae1b7 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -56,14 +56,11 @@ txt_to_synopsis () {
fi &&
b2t="$(builtin_to_txt "$builtin")" &&
sed -n \
- -e '/^\[verse\]$/,/^$/ {
+ -E '/^\[(verse|synopsis)\]$/,/^$/ {
/^$/d;
- /^\[verse\]$/d;
- s/_//g;
- s/++//g;
- s/`//g;
- s/{litdd}/--/g;
- s/'\''\(git[ a-z-]*\)'\''/\1/g;
+ /^\[(verse|synopsis)\]$/d;
+ s/\{litdd\}/--/g;
+ s/'\''(git[ a-z-]*)'\''/\1/g;
p;
}' \
--
gitgitgadget
^ permalink raw reply related [flat|nested] 45+ messages in thread* [PATCH v3 2/3] doc: update the guidelines to reflect the current formatting rules
2024-08-11 15:20 ` [PATCH v3 " Jean-Noël Avila via GitGitGadget
2024-08-11 15:20 ` [PATCH v3 1/3] doc: introduce a synopsis custom paragraph attribute Jean-Noël Avila via GitGitGadget
@ 2024-08-11 15:20 ` Jean-Noël Avila via GitGitGadget
2024-08-11 23:56 ` Eric Sunshine
2024-08-11 15:20 ` [PATCH v3 3/3] doc: apply synopsis simplification on git-clone and git-init Jean-Noël Avila via GitGitGadget
` (2 subsequent siblings)
4 siblings, 1 reply; 45+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2024-08-11 15:20 UTC (permalink / raw)
To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/CodingGuidelines | 54 ++++++++++++++++++----------------
1 file changed, 28 insertions(+), 26 deletions(-)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 1d92b2da03e..1c2d2ecbea9 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -746,70 +746,72 @@ Markup:
_<key-id>_
When literal and placeholders are mixed, each markup is applied for
- each sub-entity. If they are stuck, a special markup, called
- unconstrained formatting is required.
- Unconstrained formating for placeholders is __<like-this>__
- Unconstrained formatting for literal formatting is ++like this++
- `--jobs` _<n>_
- ++--sort=++__<key>__
- __<directory>__++/.git++
- ++remote.++__<name>__++.mirror++
-
- caveat: ++ unconstrained format is not verbatim and may expand
- content. Use Asciidoc escapes inside them.
+ each sub-entity. If the formatting is becoming too hairy, you can use the
+ s:["foo"] formatting macro and let it format the groups for you.
+ `--jobs` _<n>_ or s:["--jobs <n>"]
+ s:["--sort=<key>
+ s:["<directory>/.git"]
+ s:["remote.<name>.mirror"]
+ s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
+
+Note that the double-quotes are required by the macro.
Synopsis Syntax
- Syntax grammar is formatted neither as literal nor as placeholder.
+ The synopsis (a paragraph with [synopsis] attribute) is automatically
+ formatted by the toolchain and does not need typesetting.
A few commented examples follow to provide reference when writing or
modifying command usage strings and synopsis sections in the manual
pages:
Possibility of multiple occurrences is indicated by three dots:
- _<file>_...
+ <file>...
(One or more of <file>.)
Optional parts are enclosed in square brackets:
- [_<file>_...]
+ [<file>...]
(Zero or more of <file>.)
- ++--exec-path++[++=++__<path>__]
+ An optional parameter needs to be typeset with unconstrained pairs
+ [<repository>]
+
+ --exec-path[=<path>]
(Option with an optional argument. Note that the "=" is inside the
brackets.)
- [_<patch>_...]
+ [<patch>...]
(Zero or more of <patch>. Note that the dots are inside, not
outside the brackets.)
Multiple alternatives are indicated with vertical bars:
- [`-q` | `--quiet`]
- [`--utf8` | `--no-utf8`]
+ [-q | --quiet]
+ [--utf8 | --no-utf8]
Use spacing around "|" token(s), but not immediately after opening or
before closing a [] or () pair:
- Do: [`-q` | `--quiet`]
- Don't: [`-q`|`--quiet`]
+ Do: [-q | --quiet]
+ Don't: [-q|--quiet]
Don't use spacing around "|" tokens when they're used to separate the
alternate arguments of an option:
- Do: ++--track++[++=++(`direct`|`inherit`)]`
- Don't: ++--track++[++=++(`direct` | `inherit`)]
+ Do: --track[=(direct|inherit)]
+ Don't: --track[=(direct | inherit)]
Parentheses are used for grouping:
- [(_<rev>_ | _<range>_)...]
+ [(<rev>|<range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
it clear that "..." pertains to both <rev> and <range>.)
- [(`-p` _<parent>_)...]
+ [(-p <parent>)...]
(Any number of option -p, each with one <parent> argument.)
- `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
+ git remote set-head <name> (-a|-d|<branch>)
(One and only one of "-a", "-d" or "<branch>" _must_ (no square
brackets) be provided.)
And a somewhat more contrived example:
- `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
+ --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
Here "=" is outside the brackets, because "--diff-filter=" is a
valid usage. "*" has its own pair of brackets, because it can
(optionally) be specified only when one or more of the letters is
--
gitgitgadget
^ permalink raw reply related [flat|nested] 45+ messages in thread* Re: [PATCH v3 2/3] doc: update the guidelines to reflect the current formatting rules
2024-08-11 15:20 ` [PATCH v3 2/3] doc: update the guidelines to reflect the current formatting rules Jean-Noël Avila via GitGitGadget
@ 2024-08-11 23:56 ` Eric Sunshine
2024-08-12 6:18 ` Jean-Noël Avila
0 siblings, 1 reply; 45+ messages in thread
From: Eric Sunshine @ 2024-08-11 23:56 UTC (permalink / raw)
To: Jean-Noël Avila via GitGitGadget; +Cc: git, Jean-Noël Avila
On Sun, Aug 11, 2024 at 11:20 AM Jean-Noël Avila via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> @@ -746,70 +746,72 @@ Markup:
> When literal and placeholders are mixed, each markup is applied for
> + each sub-entity. If the formatting is becoming too hairy, you can use the
> + s:["foo"] formatting macro and let it format the groups for you.
> + `--jobs` _<n>_ or s:["--jobs <n>"]
> + s:["--sort=<key>
> + s:["<directory>/.git"]
> + s:["remote.<name>.mirror"]
> + s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
> +
> +Note that the double-quotes are required by the macro.
The closing `"]` is missing from the --sort example. Is that intentional?
^ permalink raw reply [flat|nested] 45+ messages in thread
* Re: [PATCH v3 2/3] doc: update the guidelines to reflect the current formatting rules
2024-08-11 23:56 ` Eric Sunshine
@ 2024-08-12 6:18 ` Jean-Noël Avila
0 siblings, 0 replies; 45+ messages in thread
From: Jean-Noël Avila @ 2024-08-12 6:18 UTC (permalink / raw)
To: Eric Sunshine, Jean-Noël Avila via GitGitGadget; +Cc: git
[-- Attachment #1: Type: text/plain, Size: 922 bytes --]
Le 12/08/2024 à 01:56, Eric Sunshine a écrit :
> On Sun, Aug 11, 2024 at 11:20 AM Jean-Noël Avila via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
>> ---
>> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
>> @@ -746,70 +746,72 @@ Markup:
>> When literal and placeholders are mixed, each markup is applied for
>> + each sub-entity. If the formatting is becoming too hairy, you can use the
>> + s:["foo"] formatting macro and let it format the groups for you.
>> + `--jobs` _<n>_ or s:["--jobs <n>"]
>> + s:["--sort=<key>
>> + s:["<directory>/.git"]
>> + s:["remote.<name>.mirror"]
>> + s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
>> +
>> +Note that the double-quotes are required by the macro.
>
> The closing `"]` is missing from the --sort example. Is that intentional?
Not at all. Will fix it.
Thanks
[-- Attachment #2: jean-noel_avila.vcf --]
[-- Type: text/vcard, Size: 464 bytes --]
begin:vcard
fn;quoted-printable:Jean-No=C3=ABl Avila
n;quoted-printable:Avila;Jean-No=C3=ABl
org:Scantech S.A.
adr;quoted-printable:Savoie Technolac BP 244;;B=C3=A2timent Androm=C3=A8de - 108 Avenue du Lac L=C3=A9man ; LA MOTTE SERVOLEX;;73290;France
email;internet:jean-noel.avila@scantech.com
title:Embedded systems manager
tel;work:+33 479 25 54 50
tel;cell:+33 633 04 64 18
x-mozilla-html:FALSE
url:http://www.scantech.com
version:2.1
end:vcard
^ permalink raw reply [flat|nested] 45+ messages in thread
* [PATCH v3 3/3] doc: apply synopsis simplification on git-clone and git-init
2024-08-11 15:20 ` [PATCH v3 " Jean-Noël Avila via GitGitGadget
2024-08-11 15:20 ` [PATCH v3 1/3] doc: introduce a synopsis custom paragraph attribute Jean-Noël Avila via GitGitGadget
2024-08-11 15:20 ` [PATCH v3 2/3] doc: update the guidelines to reflect the current formatting rules Jean-Noël Avila via GitGitGadget
@ 2024-08-11 15:20 ` Jean-Noël Avila via GitGitGadget
2024-08-19 20:08 ` [PATCH v3 0/3] doc: introducing synopsis para Junio C Hamano
2024-09-05 21:52 ` [PATCH v4 " Jean-Noël Avila via GitGitGadget
4 siblings, 0 replies; 45+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2024-08-11 15:20 UTC (permalink / raw)
To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
With the new synopsis formatting backend, no special asciidoc markup
is needed.
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/git-clone.txt | 76 ++++++++++++++++++-------------------
Documentation/git-init.txt | 33 +++++++---------
Documentation/urls.txt | 26 ++++++-------
3 files changed, 65 insertions(+), 70 deletions(-)
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 8e925db7e9c..f0d508ebf51 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory
SYNOPSIS
--------
-[verse]
-`git clone` [++--template=++__<template-directory>__]
- [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]
- [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]
- [`--dissociate`] [`--separate-git-dir` _<git-dir>_]
- [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]
- [++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++]
- [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]
- [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_
- [_<directory>_]
+[synopsis]
+git clone [--template=<template-directory>]
+ [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
+ [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
+ [--dissociate] [--separate-git-dir <git-dir>]
+ [--depth <depth>] [--[no-]single-branch] [--no-tags]
+ [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
+ [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
+ [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
+ [<directory>]
DESCRIPTION
-----------
@@ -64,8 +64,8 @@ prevent the unintentional copying of files by dereferencing the symbolic
links.
+
*NOTE*: this operation can race with concurrent modification to the
-source repository, similar to running `cp -r src dst` while modifying
-`src`.
+source repository, similar to running s:["cp -r <src> <dst>"] while modifying
+_<src>_.
`--no-hardlinks`::
Force the cloning process from a repository on a local
@@ -101,7 +101,7 @@ If you want to break the dependency of a repository cloned with `--shared` on
its source repository, you can simply run `git repack -a` to copy all
objects from the source repository into a pack in the cloned repository.
-`--reference`[`-if-able`] _<repository>_::
+s:["--reference[-if-able] <repository>"]::
If the reference _<repository>_ is on the local machine,
automatically setup `.git/objects/info/alternates` to
obtain objects from the reference _<repository>_. Using
@@ -142,17 +142,17 @@ objects from the source repository into a pack in the cloned repository.
is specified. This flag forces progress status even if the
standard error stream is not directed to a terminal.
-++--server-option=++__<option>__::
+s:["--server-option=<option>"]::
Transmit the given string to the server when communicating using
protocol version 2. The given string must not contain a NUL or LF
character. The server's handling of server options, including
unknown ones, is server-specific.
- When multiple ++--server-option=++__<option>__ are given, they are all
+ When multiple s:["--server-option=<option>"] are given, they are all
sent to the other side in the order listed on the command line.
`-n`::
`--no-checkout`::
- No checkout of HEAD is performed after the clone is complete.
+ No checkout of `HEAD` is performed after the clone is complete.
`--`[`no-`]`reject-shallow`::
Fail if the source repository is a shallow repository.
@@ -162,7 +162,7 @@ objects from the source repository into a pack in the cloned repository.
`--bare`::
Make a 'bare' Git repository. That is, instead of
creating _<directory>_ and placing the administrative
- files in _<directory>_`/.git`, make the _<directory>_
+ files in s:["<directory>/.git"], make the _<directory>_
itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
because there is nowhere to check out the working tree.
Also the branch heads at the remote are copied directly
@@ -177,13 +177,13 @@ objects from the source repository into a pack in the cloned repository.
linkgit:git-sparse-checkout[1] command can be used to grow the
working directory as needed.
-++--filter=++__<filter-spec>__::
+s:["--filter=<filter-spec>"]::
Use the partial clone feature and request that the server sends
a subset of reachable objects according to a given object filter.
When using `--filter`, the supplied _<filter-spec>_ is used for
the partial clone filter. For example, `--filter=blob:none` will
filter out all blobs (file contents) until needed by Git. Also,
- ++--filter=blob:limit=++__<size>__ will filter out all blobs of size
+ s:["--filter=blob:limit=<size>"] will filter out all blobs of size
at least _<size>_. For more details on filter specifications, see
the `--filter` option in linkgit:git-rev-list[1].
@@ -208,11 +208,11 @@ objects from the source repository into a pack in the cloned repository.
`-b` _<name>_::
`--branch` _<name>_::
- Instead of pointing the newly created HEAD to the branch pointed
- to by the cloned repository's HEAD, point to _<name>_ branch
+ Instead of pointing the newly created `HEAD` to the branch pointed
+ to by the cloned repository's `HEAD`, point to _<name>_ branch
instead. In a non-bare repository, this is the branch that will
be checked out.
- `--branch` can also take tags and detaches the HEAD at that commit
+ `--branch` can also take tags and detaches the `HEAD` at that commit
in the resulting repository.
`-u` _<upload-pack>_::
@@ -221,12 +221,12 @@ objects from the source repository into a pack in the cloned repository.
via ssh, this specifies a non-default path for the command
run on the other end.
-++--template=++__<template-directory>__::
+s:["--template=<template-directory>"]::
Specify the directory from which templates will be used;
(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
-`-c` __<key>__++=++__<value>__::
-`--config` __<key>__++=++__<value>__::
+`-c` s:["<key>=<value>"]::
+`--config` s:["<key>=<value>"]::
Set a configuration variable in the newly-created repository;
this takes effect immediately after the repository is
initialized, but before the remote history is fetched or any
@@ -239,25 +239,25 @@ objects from the source repository into a pack in the cloned repository.
Due to limitations of the current implementation, some configuration
variables do not take effect until after the initial fetch and checkout.
Configuration variables known to not take effect are:
-++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++. Use the
+s:["remote.<name>.mirror"] and s:["remote.<name>.tagOpt"]. Use the
corresponding `--mirror` and `--no-tags` options instead.
-`--depth` _<depth>_::
+s:["--depth <depth>"]::
Create a 'shallow' clone with a history truncated to the
specified number of commits. Implies `--single-branch` unless
`--no-single-branch` is given to fetch the histories near the
tips of all branches. If you want to clone submodules shallowly,
also pass `--shallow-submodules`.
-++--shallow-since=++__<date>__::
+s:["--shallow-since=<date>"]::
Create a shallow clone with a history after the specified time.
-++--shallow-exclude=++__<revision>__::
+s:["--shallow-exclude=<revision>"]::
Create a shallow clone with a history, excluding commits
reachable from a specified remote branch or tag. This option
can be specified multiple times.
-`--`[`no-`]`single-branch`::
+s:["--[no-]single-branch"]::
Clone only the history leading to the tip of a single branch,
either specified by the `--branch` option or the primary
branch remote's `HEAD` points at.
@@ -269,7 +269,7 @@ corresponding `--mirror` and `--no-tags` options instead.
`--no-tags`::
Don't clone any tags, and set
- `remote.<remote>.tagOpt=--no-tags` in the config, ensuring
+ s:["remote.<remote>.tagOpt=--no-tags"] in the config, ensuring
that future `git pull` and `git fetch` operations won't follow
any tags. Subsequent explicit tag fetches will still work,
(see linkgit:git-fetch[1]).
@@ -279,7 +279,7 @@ maintain a branch with no references other than a single cloned
branch. This is useful e.g. to maintain minimal clones of the default
branch of some repository for search indexing.
-`--recurse-submodules`[`=`{empty}__<pathspec>__]::
+s:["--recurse-submodules[=<pathspec>]"]::
After the clone is created, initialize and clone submodules
within based on the provided _<pathspec>_. If no _=<pathspec>_ is
provided, all submodules are initialized and cloned.
@@ -290,28 +290,28 @@ branch of some repository for search indexing.
+
Submodules are initialized and cloned using their default settings. This is
equivalent to running
-`git submodule update --init --recursive <pathspec>` immediately after
+s:["git submodule update --init --recursive <pathspec>"] immediately after
the clone is finished. This option is ignored if the cloned repository does
not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
or `--mirror` is given)
-`--`[`no-`]`shallow-submodules`::
+s:["--[no-]shallow-submodules"]::
All submodules which are cloned will be shallow with a depth of 1.
-`--`[`no-`]`remote-submodules`::
+s:["--[no-]remote-submodules"]::
All submodules which are cloned will use the status of the submodule's
remote-tracking branch to update the submodule, rather than the
superproject's recorded SHA-1. Equivalent to passing `--remote` to
`git submodule update`.
-`--separate-git-dir=`{empty}__<git-dir>__::
+s:["--separate-git-dir=<git-dir>"]::
Instead of placing the cloned repository where it is supposed
to be, place the cloned repository at the specified directory,
then make a filesystem-agnostic Git symbolic link to there.
The result is Git repository can be separated from working
tree.
-`--ref-format=`{empty}__<ref-format>__::
+s:["--ref-format=<ref-format>"]::
Specify the given ref storage format for the repository. The valid values are:
+
@@ -334,7 +334,7 @@ _<directory>_::
for `host.xz:foo/.git`). Cloning into an existing directory
is only allowed if the directory is empty.
-`--bundle-uri=`{empty}__<uri>__::
+s:["--bundle-uri=<uri>"]::
Before fetching from the remote, fetch a bundle from the given
_<uri>_ and unbundle the data into the local repository. The refs
in the bundle will be stored under the hidden `refs/bundle/*`
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index daff93bd164..fccd21cf3fb 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one
SYNOPSIS
--------
-[verse]
-`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]
- [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]
- [++--ref-format=++__<format>__]
- [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]
- [++--shared++[++=++__<permissions>__]] [_<directory>_]
+[synopsis]
+git init [-q | --quiet] [--bare] [--template=<template-directory>]
+ [--separate-git-dir <git-dir>] [--object-format=<format>]
+ [--ref-format=<format>]
+ [-b <branch-name> | --initial-branch=<branch-name>]
+ [--shared[=<permissions>]] [<directory>]
DESCRIPTION
@@ -25,11 +25,11 @@ directory with subdirectories for `objects`, `refs/heads`,
commits will be created (see the `--initial-branch` option below
for its name).
-If the `$GIT_DIR` environment variable is set then it specifies a path
+If the `GIT_DIR` environment variable is set then it specifies a path
to use instead of `./.git` for the base of the repository.
If the object storage directory is specified via the
-`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
+`GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
are created underneath; otherwise, the default `$GIT_DIR/objects`
directory is used.
@@ -51,26 +51,22 @@ Only print error and warning messages; all other output will be suppressed.
Create a bare repository. If `GIT_DIR` environment is not set, it is set to the
current working directory.
-++--object-format=++__<format>__::
-
+s:["--object-format=<format>"]::
Specify the given object _<format>_ (hash algorithm) for the repository. The valid
values are `sha1` and (if enabled) `sha256`. `sha1` is the default.
+
include::object-format-disclaimer.txt[]
-++--ref-format=++__<format>__::
-
+s:["--ref-format=<format>"]::
Specify the given ref storage _<format>_ for the repository. The valid values are:
+
include::ref-storage-format.txt[]
-++--template=++__<template-directory>__::
-
+s:["--template=<template-directory>"]::
Specify the directory from which templates will be used. (See the "TEMPLATE
DIRECTORY" section below.)
-++--separate-git-dir=++__<git-dir>__::
-
+s:["--separate-git-dir=<git-dir>"]::
Instead of initializing the repository as a directory to either `$GIT_DIR` or
`./.git/`, create a text file there containing the path to the actual
repository. This file acts as a filesystem-agnostic Git symbolic link to the
@@ -79,14 +75,13 @@ repository.
If this is a reinitialization, the repository will be moved to the specified path.
`-b` _<branch-name>_::
-++--initial-branch=++__<branch-name>__::
-
+s:["--initial-branch=<branch-name>"]::
Use _<branch-name>_ for the initial branch in the newly created
repository. If not specified, fall back to the default name (currently
`master`, but this is subject to change in the future; the name can be
customized via the `init.defaultBranch` configuration variable).
-++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::
+s:["--shared[=(false|true|umask|group|all|world|everybody|<perm>)]"]::
Specify that the Git repository is to be shared amongst several users. This
allows users belonging to the same group to push into that
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 7cec85aef17..ffeeeb3599f 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -10,19 +10,19 @@ Git supports ssh, git, http, and https protocols (in addition, ftp
and ftps can be used for fetching, but this is inefficient and
deprecated; do not use them).
-The native transport (i.e. git:// URL) does no authentication and
+The native transport (i.e. `git://` URL) does no authentication and
should be used with caution on unsecured networks.
The following syntaxes may be used with them:
-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
+- s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
+- s:["git://<host>[:<port>]/<path-to-git-repo>"]
+- s:["http[s]://<host>[:<port>]/<path-to-git-repo>"]
+- s:["ftp[s]://<host>[:<port>]/<path-to-git-repo>"]
An alternative scp-like syntax may also be used with the ssh protocol:
-- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__
+- s:["[<user>@]<host>:/<path-to-git-repo>"]
This syntax is only recognized if there are no slashes before the
first colon. This helps differentiate a local path that contains a
@@ -30,17 +30,17 @@ colon. For example the local path `foo:bar` could be specified as an
absolute path or `./foo:bar` to avoid being misinterpreted as an ssh
url.
-The ssh and git protocols additionally support ++~++__<username>__ expansion:
+The ssh and git protocols additionally support s:["~<username>"] expansion:
-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__
+- s:["ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>"]
+- s:["git://<host>[:<port>]/~<user>/<path-to-git-repo>"]
+- s:["[<user>@]<host>:~<user>/<path-to-git-repo>"]
For local repositories, also supported by Git natively, the following
syntaxes may be used:
- `/path/to/repo.git/`
-- ++file:///path/to/repo.git/++
+- `file:///path/to/repo.git/`
ifndef::git-clone[]
These two syntaxes are mostly equivalent, except when cloning, when
@@ -57,11 +57,11 @@ endif::git-clone[]
accept a suitable bundle file. See linkgit:git-bundle[1].
When Git doesn't know how to handle a certain transport protocol, it
-attempts to use the `remote-`{empty}__<transport>__ remote helper, if one
+attempts to use the s:["remote-<transport>"] remote helper, if one
exists. To explicitly request a remote helper, the following syntax
may be used:
-- _<transport>_::__<address>__
+- s:["<transport>::<address>"]
where _<address>_ may be a path, a server and path, or an arbitrary
URL-like string recognized by the specific remote helper being
--
gitgitgadget
^ permalink raw reply related [flat|nested] 45+ messages in thread* Re: [PATCH v3 0/3] doc: introducing synopsis para
2024-08-11 15:20 ` [PATCH v3 " Jean-Noël Avila via GitGitGadget
` (2 preceding siblings ...)
2024-08-11 15:20 ` [PATCH v3 3/3] doc: apply synopsis simplification on git-clone and git-init Jean-Noël Avila via GitGitGadget
@ 2024-08-19 20:08 ` Junio C Hamano
2024-08-21 21:05 ` Jean-Noël AVILA
2024-09-05 21:52 ` [PATCH v4 " Jean-Noël Avila via GitGitGadget
4 siblings, 1 reply; 45+ messages in thread
From: Junio C Hamano @ 2024-08-19 20:08 UTC (permalink / raw)
To: git
Cc: Jean-Noël Avila via GitGitGadget, Jean-Noël Avila,
Johannes Sixt, Patrick Steinhardt, Eric Sunshine
"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> Jean-Noël Avila (3):
> doc: introduce a synopsis custom paragraph attribute
> doc: update the guidelines to reflect the current formatting rules
> doc: apply synopsis simplification on git-clone and git-init
This topic has become quiet. I still find s:["someything you really
want to say"] notation a bit annoying to my eyes, but its may be the
best compromise we can come up with.
So unless we have a strong objection, or (even better) an objection
with an alternative that is less yucky, perhaps it is time to
declare that this is the variant of AsciiDoc/Asciidoctor that we'd
adopt for our documentation. Comments?
Thanks.
^ permalink raw reply [flat|nested] 45+ messages in thread* Re: [PATCH v3 0/3] doc: introducing synopsis para
2024-08-19 20:08 ` [PATCH v3 0/3] doc: introducing synopsis para Junio C Hamano
@ 2024-08-21 21:05 ` Jean-Noël AVILA
2024-08-30 17:48 ` Junio C Hamano
0 siblings, 1 reply; 45+ messages in thread
From: Jean-Noël AVILA @ 2024-08-21 21:05 UTC (permalink / raw)
To: git, Junio C Hamano
Cc: Jean-Noël Avila via GitGitGadget, Johannes Sixt,
Patrick Steinhardt, Eric Sunshine
Le lundi 19 août 2024, 22:08:19 CEST Junio C Hamano a écrit :
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > Jean-Noël Avila (3):
> > doc: introduce a synopsis custom paragraph attribute
> > doc: update the guidelines to reflect the current formatting rules
> > doc: apply synopsis simplification on git-clone and git-init
>
> This topic has become quiet. I still find s:["someything you really
> want to say"] notation a bit annoying to my eyes, but its may be the
> best compromise we can come up with.
>
> So unless we have a strong objection, or (even better) an objection
> with an alternative that is less yucky, perhaps it is time to
> declare that this is the variant of AsciiDoc/Asciidoctor that we'd
> adopt for our documentation. Comments?
>
> Thanks.
>
I understand that you are reluctant to include a change that, as the
maintainer, you do not feel comfortable keeping alive.
The whole discussion thread tells me that other developers are not ready to go
down the "full markup" path. Understandably, this makes it more difficult for
everyone to propose changes and review them, as there's no tool to track such
formatting errors and we have to rely on careful manual cross-checking.
I would like to thank you for pushing so that the markup can be simplified as
much as can be. It can be simplified further one step further: it is possible
both in asciidoc/asciidoctor to override the formatting of inline verbatim
texts, so that everything that is backquoted is processed as a synopsis
string.
This way, strings like
`<commit>`
`diff.statGraphWidth=<width>`
` --dirstat-by-file[=<param>,...]`
are automatically rendered with the expected styles.
However, contrary to the s macro, this is quite disruptive as it forces the
new processing on all existing manpages. Another drawback is that it is no
longer genuine asciidoc, but it seems more in line with the critics. I'm
refining the regexp at the moment to check for side-effects.
Is this proposition more appropriate?
^ permalink raw reply [flat|nested] 45+ messages in thread
* Re: [PATCH v3 0/3] doc: introducing synopsis para
2024-08-21 21:05 ` Jean-Noël AVILA
@ 2024-08-30 17:48 ` Junio C Hamano
0 siblings, 0 replies; 45+ messages in thread
From: Junio C Hamano @ 2024-08-30 17:48 UTC (permalink / raw)
To: Jean-Noël AVILA
Cc: git, Jean-Noël Avila via GitGitGadget, Johannes Sixt,
Patrick Steinhardt, Eric Sunshine
Jean-Noël AVILA <jn.avila@free.fr> writes:
> ... It can be simplified further one step further: it is possible
> both in asciidoc/asciidoctor to override the formatting of inline verbatim
> texts, so that everything that is backquoted is processed as a synopsis
> string.
> This way, strings like
>
> `<commit>`
> `diff.statGraphWidth=<width>`
> ` --dirstat-by-file[=<param>,...]`
>
> are automatically rendered with the expected styles.
>
> However, contrary to the s macro, this is quite disruptive as it forces the
> new processing on all existing manpages. Another drawback is that it is no
> longer genuine asciidoc, but it seems more in line with the critics. I'm
> refining the regexp at the moment to check for side-effects.
>
> Is this proposition more appropriate?
Thanks for thinking these things through. The fact that such a
"magic" processing will hide the gory details from those whose
primary interest is to describe the commands and their options cuts
both ways. It is a very welcome thing for developers around here, I
would assume. At the same time, I can understand that purists would
find it unacceptably ugly, as `backticks` is now much more than a
mark-up that means "this text is typeset in monospace". Inside it,
<text inside angle brackets>, [optional text], and (choices), all
signal that they have special meaning by being typeset differently.
I do not personally mind that, and I would even dream about a future
in which other projects notice what you did to AsciiDoctor, love it,
adopt it, and eventually it feeds back to improve AsciiDoctor proper.
It is very likely that is because I haven't seen any "side effects"
yet ;-)
Thanks.
^ permalink raw reply [flat|nested] 45+ messages in thread
* [PATCH v4 0/3] doc: introducing synopsis para
2024-08-11 15:20 ` [PATCH v3 " Jean-Noël Avila via GitGitGadget
` (3 preceding siblings ...)
2024-08-19 20:08 ` [PATCH v3 0/3] doc: introducing synopsis para Junio C Hamano
@ 2024-09-05 21:52 ` Jean-Noël Avila via GitGitGadget
2024-09-05 21:52 ` [PATCH v4 1/3] doc: introduce a synopsis typesetting Jean-Noël Avila via GitGitGadget
` (4 more replies)
4 siblings, 5 replies; 45+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2024-09-05 21:52 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Jean-Noël Avila
In the continuation of the simplification of manpage editing, the synopsis
processing that was developed for synopsis paragraph style is also applied
to all inline backquoted texts.
Refining the magic regexp took more time than expected, but this one should
really enhance writers'experience. I had to fight a bit more with
asciidoctor, due to discrepancies between version 2.0 on my laptop and the
1.5.6 used by Github actions.
The git-init and git-clone manpages are converted to this new system.
Changes since V1:
* switch to sed for asciidoc filter and refine the regex for support under
macOS
Changes since V2:
* introduce the s macro to freely apply synopsis styling wherever needed,
without formatting hassle.
Changes since V3:
* replace s macro by direct processing of literal text at the level of
output processors.
Jean-Noël Avila (3):
doc: introduce a synopsis typesetting
doc: update the guidelines to reflect the current formatting rules
doc: apply synopsis simplification on git-clone and git-init
Documentation/CodingGuidelines | 58 +++++++++--------
Documentation/asciidoc.conf | 20 ++++++
Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++
Documentation/git-clone.txt | 78 +++++++++++-----------
Documentation/git-init.txt | 35 +++++-----
Documentation/urls.txt | 26 ++++----
ci/install-dependencies.sh | 1 +
t/t0450-txt-doc-vs-help.sh | 11 ++--
8 files changed, 209 insertions(+), 107 deletions(-)
base-commit: 2e7b89e038c0c888acf61f1b4ee5a43d4dd5e94c
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1766%2Fjnavila%2Fdoc_synopsis_para-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1766/jnavila/doc_synopsis_para-v4
Pull-Request: https://github.com/gitgitgadget/git/pull/1766
Range-diff vs v3:
1: 0d7c1dd8f26 ! 1: c09968d7ccb doc: introduce a synopsis custom paragraph attribute
@@ Metadata
Author: Jean-Noël Avila <jn.avila@free.fr>
## Commit message ##
- doc: introduce a synopsis custom paragraph attribute
+ doc: introduce a synopsis typesetting
In order to follow the common manpage usage, the synopsis of the
commands needs to be heavily typeset. A first try was performed with
@@ Commit message
In order to both simplify the writer's task and obtain a consistant
typesetting in the synopsis, a custom 'synopsis' paragraph type is
- created and the backends of asciidoc and asciidoctor take in charge to
- correctly add the required typesetting.
-
- additionally, a 's' macro ('s' standing for synopsis) is introduced to
- allow writers to freely apply automatic styling whereever required.
+ created and the processor for backticked text are modified. The
+ backends of asciidoc and asciidoctor take in charge to correctly add
+ the required typesetting.
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
## Documentation/asciidoc.conf ##
-@@
-
- [macros]
- (?su)[\\]?(?P<name>linkgit):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
--
-+(?su)[\\]?(?P<name>s):(?P<target>\S*?)\["(?P<attrlist>.*?)"\]=
- [attributes]
- asterisk=*
- plus=+
@@ Documentation/asciidoc.conf: ifdef::backend-docbook[]
{0#<citerefentry>}
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
{0#</citerefentry>}
+
-+[s-inlinemacro]
-+{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<emphasis>\1</emphasis>', re.sub(r'([\[ |()>]|^|\]|>)(\.?[-a-zA-Z0-9:+=~@,\/]+\.?)',r'\1<literal>\2</literal>', '{attrlist}'))}
++[literal-inlinemacro]
++{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
++
endif::backend-docbook[]
ifdef::backend-docbook[]
@@ Documentation/asciidoc.conf: ifdef::backend-xhtml11[]
[linkgit-inlinemacro]
<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
+
-+[s-inlinemacro]
-+{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<em>\1</em>', re.sub(r'([\[ |()>]|^|\]|>)(\.?[-=a-zA-Z0-9:+,@]+\.?)',r'\1<code>\2</code>', '{attrlist}'))}
++[literal-inlinemacro]
++{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
+
+endif::backend-xhtml11[]
+
+ifdef::backend-docbook[]
+ifdef::doctype-manpage[]
+[paradef-default]
-+synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@]+\.?+)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]+>!<emphasis>\\0</emphasis>!g'"
++synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@,\/_^\$]+\.?+)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]+>!<emphasis>\\0</emphasis>!g'"
+endif::doctype-manpage[]
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[paradef-default]
-+synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@]+\.?)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]+>!<em>\\0</em>!g'"
++synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@,\/_^\$]+\.?)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]+>!<em>\\0</em>!g'"
endif::backend-xhtml11[]
## Documentation/asciidoctor-extensions.rb ##
-@@ Documentation/asciidoctor-extensions.rb: module Git
- end
- end
+@@
+ require 'asciidoctor'
+ require 'asciidoctor/extensions'
++require 'asciidoctor/converter/docbook5'
++require 'asciidoctor/converter/html5'
-+ class SynopsisMacroProcessor < Asciidoctor::Extensions::InlineMacroProcessor
-+ use_dsl
-+
-+ named :s
-+ match(/s:\["(.+?)"\]/)
-+
-+ def process(parent, target, attrs)
-+ l = target.gsub(/([\[\] |()]|^|>)(\.?[-a-zA-Z0-9:+=~@,\/]+\.?)/, '\1{empty}`\2`{empty}')
-+ .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
-+ .gsub(']', ']{empty}')
-+
-+ create_inline parent, :quoted, l, attributes: { 'subs' => :normal }
-+ end
-+ end
-+
- class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor
- def process document, output
- if document.basebackend? 'docbook'
+ module Git
+ module Documentation
@@ Documentation/asciidoctor-extensions.rb: module Git
output
end
@@ Documentation/asciidoctor-extensions.rb: module Git
+
+ def process parent, reader, attrs
+ outlines = reader.lines.map do |l|
-+ l.gsub(/([\[\] |()>]|^)([-a-zA-Z0-9:+=]+)/, '\1{empty}`\2`{empty}')
++ l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2')
++ .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}')
+ .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
+ .gsub(']', ']{empty}')
+ end
+ create_block parent, :verse, outlines, attrs
+ end
++ end
++
++ class GitDBConverter < Asciidoctor::Converter::DocBook5Converter
++
++ extend Asciidoctor::Converter::Config
++ register_for 'docbook5'
++
++ def convert_inline_quoted node
++ if (type = node.type) == :asciimath
++ # NOTE fop requires jeuclid to process mathml markup
++ asciimath_available? ? %(<inlineequation>#{(::AsciiMath.parse node.text).to_mathml 'mml:', 'xmlns:mml' => 'http://www.w3.org/1998/Math/MathML'}</inlineequation>) : %(<inlineequation><mathphrase><![CDATA[#{node.text}]]></mathphrase></inlineequation>)
++ elsif type == :latexmath
++ # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math
++ %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
++ elsif type == :monospaced
++ node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
++ .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
++ .gsub(/(<[-a-zA-Z0-9.]+>)/, '<emphasis>\1</emphasis>')
++ else
++ open, close, supports_phrase = QUOTE_TAGS[type]
++ text = node.text
++ if node.role
++ if supports_phrase
++ quoted_text = %(#{open}<phrase role="#{node.role}">#{text}</phrase>#{close})
++ else
++ quoted_text = %(#{open.chop} role="#{node.role}">#{text}#{close})
++ end
++ else
++ quoted_text = %(#{open}#{text}#{close})
++ end
++ node.id ? %(<anchor#{common_attributes node.id, nil, text}/>#{quoted_text}) : quoted_text
++ end
++ end
++ end
++
++ # register a html5 converter that takes in charge to convert monospaced text into Git style synopsis
++ class GitHTMLConverter < Asciidoctor::Converter::Html5Converter
++
++ extend Asciidoctor::Converter::Config
++ register_for 'html5'
++
++ def convert_inline_quoted node
++ if node.type == :monospaced
++ node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
++ .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
++ .gsub(/(<[-a-zA-Z0-9.]+>)/, '<em>\1</em>')
++
++ else
++ open, close, tag = QUOTE_TAGS[node.type]
++ if node.id
++ class_attr = node.role ? %( class="#{node.role}") : ''
++ if tag
++ %(#{open.chop} id="#{node.id}"#{class_attr}>#{node.text}#{close})
++ else
++ %(<span id="#{node.id}"#{class_attr}>#{open}#{node.text}#{close}</span>)
++ end
++ elsif node.role
++ if tag
++ %(#{open.chop} class="#{node.role}">#{node.text}#{close})
++ else
++ %(<span class="#{node.role}">#{open}#{node.text}#{close}</span>)
++ end
++ else
++ %(#{open}#{node.text}#{close})
++ end
++ end
++ end
+ end
end
end
Asciidoctor::Extensions.register do
inline_macro Git::Documentation::LinkGitProcessor, :linkgit
-+ inline_macro Git::Documentation::SynopsisMacroProcessor
+ block Git::Documentation::SynopsisBlock
postprocessor Git::Documentation::DocumentPostProcessor
end
+ ## ci/install-dependencies.sh ##
+@@ ci/install-dependencies.sh: Documentation)
+
+ test -n "$ALREADY_HAVE_ASCIIDOCTOR" ||
+ sudo gem install --version 1.5.8 asciidoctor
++ sudo gem install concurrent-ruby
+ ;;
+ esac
+
+
## t/t0450-txt-doc-vs-help.sh ##
@@ t/t0450-txt-doc-vs-help.sh: txt_to_synopsis () {
fi &&
2: 92f3121cf4e ! 2: c48649ccd63 doc: update the guidelines to reflect the current formatting rules
@@ Commit message
## Documentation/CodingGuidelines ##
@@ Documentation/CodingGuidelines: Markup:
+ _<new-branch-name>_
+ _<template-directory>_
+
+- A placeholder is not enclosed in backticks, as it is not a literal.
+-
+ When needed, use a distinctive identifier for placeholders, usually
+ made of a qualification and a type:
+ _<git-dir>_
_<key-id>_
- When literal and placeholders are mixed, each markup is applied for
+- When literal and placeholders are mixed, each markup is applied for
- each sub-entity. If they are stuck, a special markup, called
- unconstrained formatting is required.
- Unconstrained formating for placeholders is __<like-this>__
@@ Documentation/CodingGuidelines: Markup:
- ++--sort=++__<key>__
- __<directory>__++/.git++
- ++remote.++__<name>__++.mirror++
--
++ Git's Asciidoc processor has been tailored to treat backticked text
++ as complex synopsis. When literal and placeholders are mixed, you can
++ use the backtick notation which will take care of correctly typesetting
++ the content.
++ `--jobs <n>`
++ `--sort=<key>`
++ `<directory>/.git`
++ `remote.<name>.mirror`
++ `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
+
- caveat: ++ unconstrained format is not verbatim and may expand
- content. Use Asciidoc escapes inside them.
-+ each sub-entity. If the formatting is becoming too hairy, you can use the
-+ s:["foo"] formatting macro and let it format the groups for you.
-+ `--jobs` _<n>_ or s:["--jobs <n>"]
-+ s:["--sort=<key>
-+ s:["<directory>/.git"]
-+ s:["remote.<name>.mirror"]
-+ s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
-+
-+Note that the double-quotes are required by the macro.
++As a side effect, backquoted placeholders are correctly typeset, but
++this style is not recommended.
Synopsis Syntax
3: 02406b91894 ! 3: 719188da711 doc: apply synopsis simplification on git-clone and git-init
@@ Documentation/git-clone.txt: git-clone - Clone a repository into a new directory
DESCRIPTION
-----------
+@@ Documentation/git-clone.txt: OPTIONS
+ to save space when possible.
+ +
+ If the repository is specified as a local path (e.g., `/path/to/repo`),
+-this is the default, and --local is essentially a no-op. If the
++this is the default, and `--local` is essentially a no-op. If the
+ repository is specified as a URL, then this flag is ignored (and we
+ never use the local optimizations). Specifying `--no-local` will
+ override the default when `/path/to/repo` is given, using the regular
@@ Documentation/git-clone.txt: prevent the unintentional copying of files by dereferencing the symbolic
links.
+
*NOTE*: this operation can race with concurrent modification to the
-source repository, similar to running `cp -r src dst` while modifying
-`src`.
-+source repository, similar to running s:["cp -r <src> <dst>"] while modifying
++source repository, similar to running `cp -r <src> <dst>` while modifying
+_<src>_.
`--no-hardlinks`::
@@ Documentation/git-clone.txt: If you want to break the dependency of a repository
objects from the source repository into a pack in the cloned repository.
-`--reference`[`-if-able`] _<repository>_::
-+s:["--reference[-if-able] <repository>"]::
++`--reference[-if-able] <repository>`::
If the reference _<repository>_ is on the local machine,
automatically setup `.git/objects/info/alternates` to
obtain objects from the reference _<repository>_. Using
@@ Documentation/git-clone.txt: objects from the source repository into a pack in t
standard error stream is not directed to a terminal.
-++--server-option=++__<option>__::
-+s:["--server-option=<option>"]::
++`--server-option=<option>`::
Transmit the given string to the server when communicating using
protocol version 2. The given string must not contain a NUL or LF
character. The server's handling of server options, including
unknown ones, is server-specific.
- When multiple ++--server-option=++__<option>__ are given, they are all
-+ When multiple s:["--server-option=<option>"] are given, they are all
++ When multiple `--server-option=<option>` are given, they are all
sent to the other side in the order listed on the command line.
`-n`::
@@ Documentation/git-clone.txt: objects from the source repository into a pack in t
Make a 'bare' Git repository. That is, instead of
creating _<directory>_ and placing the administrative
- files in _<directory>_`/.git`, make the _<directory>_
-+ files in s:["<directory>/.git"], make the _<directory>_
++ files in `<directory>/.git`, make the _<directory>_
itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
because there is nowhere to check out the working tree.
Also the branch heads at the remote are copied directly
@@ Documentation/git-clone.txt: objects from the source repository into a pack in t
working directory as needed.
-++--filter=++__<filter-spec>__::
-+s:["--filter=<filter-spec>"]::
++`--filter=<filter-spec>`::
Use the partial clone feature and request that the server sends
a subset of reachable objects according to a given object filter.
When using `--filter`, the supplied _<filter-spec>_ is used for
the partial clone filter. For example, `--filter=blob:none` will
filter out all blobs (file contents) until needed by Git. Also,
- ++--filter=blob:limit=++__<size>__ will filter out all blobs of size
-+ s:["--filter=blob:limit=<size>"] will filter out all blobs of size
++ `--filter=blob:limit=<size>` will filter out all blobs of size
at least _<size>_. For more details on filter specifications, see
the `--filter` option in linkgit:git-rev-list[1].
@@ Documentation/git-clone.txt: objects from the source repository into a pack in t
run on the other end.
-++--template=++__<template-directory>__::
-+s:["--template=<template-directory>"]::
++`--template=<template-directory>`::
Specify the directory from which templates will be used;
(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
-`-c` __<key>__++=++__<value>__::
-`--config` __<key>__++=++__<value>__::
-+`-c` s:["<key>=<value>"]::
-+`--config` s:["<key>=<value>"]::
++`-c` `<key>=<value>`::
++`--config` `<key>=<value>`::
Set a configuration variable in the newly-created repository;
this takes effect immediately after the repository is
initialized, but before the remote history is fetched or any
@@ Documentation/git-clone.txt: objects from the source repository into a pack in t
variables do not take effect until after the initial fetch and checkout.
Configuration variables known to not take effect are:
-++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++. Use the
-+s:["remote.<name>.mirror"] and s:["remote.<name>.tagOpt"]. Use the
++`remote.<name>.mirror` and `remote.<name>.tagOpt`. Use the
corresponding `--mirror` and `--no-tags` options instead.
-`--depth` _<depth>_::
-+s:["--depth <depth>"]::
++`--depth <depth>`::
Create a 'shallow' clone with a history truncated to the
specified number of commits. Implies `--single-branch` unless
`--no-single-branch` is given to fetch the histories near the
@@ Documentation/git-clone.txt: objects from the source repository into a pack in t
also pass `--shallow-submodules`.
-++--shallow-since=++__<date>__::
-+s:["--shallow-since=<date>"]::
++`--shallow-since=<date>`::
Create a shallow clone with a history after the specified time.
-++--shallow-exclude=++__<revision>__::
-+s:["--shallow-exclude=<revision>"]::
++`--shallow-exclude=<revision>`::
Create a shallow clone with a history, excluding commits
reachable from a specified remote branch or tag. This option
can be specified multiple times.
-`--`[`no-`]`single-branch`::
-+s:["--[no-]single-branch"]::
++`--[no-]single-branch`::
Clone only the history leading to the tip of a single branch,
either specified by the `--branch` option or the primary
branch remote's `HEAD` points at.
-@@ Documentation/git-clone.txt: corresponding `--mirror` and `--no-tags` options instead.
-
- `--no-tags`::
- Don't clone any tags, and set
-- `remote.<remote>.tagOpt=--no-tags` in the config, ensuring
-+ s:["remote.<remote>.tagOpt=--no-tags"] in the config, ensuring
- that future `git pull` and `git fetch` operations won't follow
- any tags. Subsequent explicit tag fetches will still work,
- (see linkgit:git-fetch[1]).
@@ Documentation/git-clone.txt: maintain a branch with no references other than a single cloned
branch. This is useful e.g. to maintain minimal clones of the default
branch of some repository for search indexing.
-`--recurse-submodules`[`=`{empty}__<pathspec>__]::
-+s:["--recurse-submodules[=<pathspec>]"]::
++`--recurse-submodules[=<pathspec>]`::
After the clone is created, initialize and clone submodules
- within based on the provided _<pathspec>_. If no _=<pathspec>_ is
+- within based on the provided _<pathspec>_. If no _=<pathspec>_ is
++ within based on the provided _<pathspec>_. If no `=<pathspec>` is
provided, all submodules are initialized and cloned.
-@@ Documentation/git-clone.txt: branch of some repository for search indexing.
+ This option can be given multiple times for pathspecs consisting
+ of multiple entries. The resulting clone has `submodule.active` set to
+- the provided pathspec, or "." (meaning all submodules) if no
++ the provided pathspec, or "`.`" (meaning all submodules) if no
+ pathspec is provided.
+
Submodules are initialized and cloned using their default settings. This is
- equivalent to running
--`git submodule update --init --recursive <pathspec>` immediately after
-+s:["git submodule update --init --recursive <pathspec>"] immediately after
- the clone is finished. This option is ignored if the cloned repository does
+@@ Documentation/git-clone.txt: the clone is finished. This option is ignored if the cloned repository does
not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
or `--mirror` is given)
-`--`[`no-`]`shallow-submodules`::
-+s:["--[no-]shallow-submodules"]::
++`--[no-]shallow-submodules`::
All submodules which are cloned will be shallow with a depth of 1.
-`--`[`no-`]`remote-submodules`::
-+s:["--[no-]remote-submodules"]::
++`--[no-]remote-submodules`::
All submodules which are cloned will use the status of the submodule's
remote-tracking branch to update the submodule, rather than the
superproject's recorded SHA-1. Equivalent to passing `--remote` to
`git submodule update`.
-`--separate-git-dir=`{empty}__<git-dir>__::
-+s:["--separate-git-dir=<git-dir>"]::
++`--separate-git-dir=<git-dir>`::
Instead of placing the cloned repository where it is supposed
to be, place the cloned repository at the specified directory,
then make a filesystem-agnostic Git symbolic link to there.
@@ Documentation/git-clone.txt: branch of some repository for search indexing.
tree.
-`--ref-format=`{empty}__<ref-format>__::
-+s:["--ref-format=<ref-format>"]::
++`--ref-format=<ref-format>`::
Specify the given ref storage format for the repository. The valid values are:
+
@@ Documentation/git-clone.txt: _<directory>_::
is only allowed if the directory is empty.
-`--bundle-uri=`{empty}__<uri>__::
-+s:["--bundle-uri=<uri>"]::
++`--bundle-uri=<uri>`::
Before fetching from the remote, fetch a bundle from the given
_<uri>_ and unbundle the data into the local repository. The refs
in the bundle will be stored under the hidden `refs/bundle/*`
@@ Documentation/git-init.txt: Only print error and warning messages; all other out
-++--object-format=++__<format>__::
-
-+s:["--object-format=<format>"]::
++`--object-format=<format>`::
Specify the given object _<format>_ (hash algorithm) for the repository. The valid
values are `sha1` and (if enabled) `sha256`. `sha1` is the default.
+
@@ Documentation/git-init.txt: Only print error and warning messages; all other out
-++--ref-format=++__<format>__::
-
-+s:["--ref-format=<format>"]::
++`--ref-format=<format>`::
Specify the given ref storage _<format>_ for the repository. The valid values are:
+
include::ref-storage-format.txt[]
-++--template=++__<template-directory>__::
-
-+s:["--template=<template-directory>"]::
++`--template=<template-directory>`::
Specify the directory from which templates will be used. (See the "TEMPLATE
DIRECTORY" section below.)
-++--separate-git-dir=++__<git-dir>__::
-
-+s:["--separate-git-dir=<git-dir>"]::
++`--separate-git-dir=<git-dir>`::
Instead of initializing the repository as a directory to either `$GIT_DIR` or
`./.git/`, create a text file there containing the path to the actual
repository. This file acts as a filesystem-agnostic Git symbolic link to the
@@ Documentation/git-init.txt: repository.
+ +
If this is a reinitialization, the repository will be moved to the specified path.
- `-b` _<branch-name>_::
+-`-b` _<branch-name>_::
-++--initial-branch=++__<branch-name>__::
-
-+s:["--initial-branch=<branch-name>"]::
++`-b <branch-name>`::
++`--initial-branch=<branch-name>`::
Use _<branch-name>_ for the initial branch in the newly created
repository. If not specified, fall back to the default name (currently
`master`, but this is subject to change in the future; the name can be
customized via the `init.defaultBranch` configuration variable).
-++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::
-+s:["--shared[=(false|true|umask|group|all|world|everybody|<perm>)]"]::
++`--shared[=(false|true|umask|group|all|world|everybody|<perm>)]`::
Specify that the Git repository is to be shared amongst several users. This
allows users belonging to the same group to push into that
@@ Documentation/urls.txt: Git supports ssh, git, http, and https protocols (in add
-- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-+- s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
-+- s:["git://<host>[:<port>]/<path-to-git-repo>"]
-+- s:["http[s]://<host>[:<port>]/<path-to-git-repo>"]
-+- s:["ftp[s]://<host>[:<port>]/<path-to-git-repo>"]
++- `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
++- `git://<host>[:<port>]/<path-to-git-repo>`
++- `http[s]://<host>[:<port>]/<path-to-git-repo>`
++- `ftp[s]://<host>[:<port>]/<path-to-git-repo>`
An alternative scp-like syntax may also be used with the ssh protocol:
-- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__
-+- s:["[<user>@]<host>:/<path-to-git-repo>"]
++- `[<user>@]<host>:/<path-to-git-repo>`
This syntax is only recognized if there are no slashes before the
first colon. This helps differentiate a local path that contains a
@@ Documentation/urls.txt: colon. For example the local path `foo:bar` could be spe
url.
-The ssh and git protocols additionally support ++~++__<username>__ expansion:
-+The ssh and git protocols additionally support s:["~<username>"] expansion:
++The ssh and git protocols additionally support `~<username>` expansion:
-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__
-+- s:["ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>"]
-+- s:["git://<host>[:<port>]/~<user>/<path-to-git-repo>"]
-+- s:["[<user>@]<host>:~<user>/<path-to-git-repo>"]
++- `ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>`
++- `git://<host>[:<port>]/~<user>/<path-to-git-repo>`
++- `[<user>@]<host>:~<user>/<path-to-git-repo>`
For local repositories, also supported by Git natively, the following
syntaxes may be used:
@@ Documentation/urls.txt: endif::git-clone[]
When Git doesn't know how to handle a certain transport protocol, it
-attempts to use the `remote-`{empty}__<transport>__ remote helper, if one
-+attempts to use the s:["remote-<transport>"] remote helper, if one
++attempts to use the `remote-<transport>` remote helper, if one
exists. To explicitly request a remote helper, the following syntax
may be used:
-- _<transport>_::__<address>__
-+- s:["<transport>::<address>"]
++- `<transport>::<address>`
where _<address>_ may be a path, a server and path, or an arbitrary
URL-like string recognized by the specific remote helper being
--
gitgitgadget
^ permalink raw reply [flat|nested] 45+ messages in thread* [PATCH v4 1/3] doc: introduce a synopsis typesetting
2024-09-05 21:52 ` [PATCH v4 " Jean-Noël Avila via GitGitGadget
@ 2024-09-05 21:52 ` Jean-Noël Avila via GitGitGadget
2024-09-05 21:52 ` [PATCH v4 2/3] doc: update the guidelines to reflect the current formatting rules Jean-Noël Avila via GitGitGadget
` (3 subsequent siblings)
4 siblings, 0 replies; 45+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2024-09-05 21:52 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Jean-Noël Avila, Jean-Noël Avila
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
In order to follow the common manpage usage, the synopsis of the
commands needs to be heavily typeset. A first try was performed with
using native markup, but it turned out to make the document source
almost unreadable, difficult to write and prone to mistakes with
unwanted Asciidoc's role attributes.
In order to both simplify the writer's task and obtain a consistant
typesetting in the synopsis, a custom 'synopsis' paragraph type is
created and the processor for backticked text are modified. The
backends of asciidoc and asciidoctor take in charge to correctly add
the required typesetting.
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/asciidoc.conf | 20 ++++++
Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++
ci/install-dependencies.sh | 1 +
t/t0450-txt-doc-vs-help.sh | 11 ++--
4 files changed, 112 insertions(+), 7 deletions(-)
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 60f76f43eda..75ae9f3da92 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -28,6 +28,10 @@ ifdef::backend-docbook[]
{0#<citerefentry>}
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
{0#</citerefentry>}
+
+[literal-inlinemacro]
+{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
+
endif::backend-docbook[]
ifdef::backend-docbook[]
@@ -56,4 +60,20 @@ ifdef::backend-xhtml11[]
git-relative-html-prefix=
[linkgit-inlinemacro]
<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
+
+[literal-inlinemacro]
+{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
+
+endif::backend-xhtml11[]
+
+ifdef::backend-docbook[]
+ifdef::doctype-manpage[]
+[paradef-default]
+synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@,\/_^\$]+\.?+)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]+>!<emphasis>\\0</emphasis>!g'"
+endif::doctype-manpage[]
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[paradef-default]
+synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@,\/_^\$]+\.?)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]+>!<em>\\0</em>!g'"
endif::backend-xhtml11[]
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index d906a008039..cb24480b63d 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -1,5 +1,7 @@
require 'asciidoctor'
require 'asciidoctor/extensions'
+require 'asciidoctor/converter/docbook5'
+require 'asciidoctor/converter/html5'
module Git
module Documentation
@@ -39,10 +41,95 @@ module Git
output
end
end
+
+ class SynopsisBlock < Asciidoctor::Extensions::BlockProcessor
+
+ use_dsl
+ named :synopsis
+ parse_content_as :simple
+
+ def process parent, reader, attrs
+ outlines = reader.lines.map do |l|
+ l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2')
+ .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}')
+ .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
+ .gsub(']', ']{empty}')
+ end
+ create_block parent, :verse, outlines, attrs
+ end
+ end
+
+ class GitDBConverter < Asciidoctor::Converter::DocBook5Converter
+
+ extend Asciidoctor::Converter::Config
+ register_for 'docbook5'
+
+ def convert_inline_quoted node
+ if (type = node.type) == :asciimath
+ # NOTE fop requires jeuclid to process mathml markup
+ asciimath_available? ? %(<inlineequation>#{(::AsciiMath.parse node.text).to_mathml 'mml:', 'xmlns:mml' => 'http://www.w3.org/1998/Math/MathML'}</inlineequation>) : %(<inlineequation><mathphrase><![CDATA[#{node.text}]]></mathphrase></inlineequation>)
+ elsif type == :latexmath
+ # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math
+ %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
+ elsif type == :monospaced
+ node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
+ .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
+ .gsub(/(<[-a-zA-Z0-9.]+>)/, '<emphasis>\1</emphasis>')
+ else
+ open, close, supports_phrase = QUOTE_TAGS[type]
+ text = node.text
+ if node.role
+ if supports_phrase
+ quoted_text = %(#{open}<phrase role="#{node.role}">#{text}</phrase>#{close})
+ else
+ quoted_text = %(#{open.chop} role="#{node.role}">#{text}#{close})
+ end
+ else
+ quoted_text = %(#{open}#{text}#{close})
+ end
+ node.id ? %(<anchor#{common_attributes node.id, nil, text}/>#{quoted_text}) : quoted_text
+ end
+ end
+ end
+
+ # register a html5 converter that takes in charge to convert monospaced text into Git style synopsis
+ class GitHTMLConverter < Asciidoctor::Converter::Html5Converter
+
+ extend Asciidoctor::Converter::Config
+ register_for 'html5'
+
+ def convert_inline_quoted node
+ if node.type == :monospaced
+ node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
+ .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
+ .gsub(/(<[-a-zA-Z0-9.]+>)/, '<em>\1</em>')
+
+ else
+ open, close, tag = QUOTE_TAGS[node.type]
+ if node.id
+ class_attr = node.role ? %( class="#{node.role}") : ''
+ if tag
+ %(#{open.chop} id="#{node.id}"#{class_attr}>#{node.text}#{close})
+ else
+ %(<span id="#{node.id}"#{class_attr}>#{open}#{node.text}#{close}</span>)
+ end
+ elsif node.role
+ if tag
+ %(#{open.chop} class="#{node.role}">#{node.text}#{close})
+ else
+ %(<span class="#{node.role}">#{open}#{node.text}#{close}</span>)
+ end
+ else
+ %(#{open}#{node.text}#{close})
+ end
+ end
+ end
+ end
end
end
Asciidoctor::Extensions.register do
inline_macro Git::Documentation::LinkGitProcessor, :linkgit
+ block Git::Documentation::SynopsisBlock
postprocessor Git::Documentation::DocumentPostProcessor
end
diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh
index 4781cd20bb0..3e3ae39cbb1 100755
--- a/ci/install-dependencies.sh
+++ b/ci/install-dependencies.sh
@@ -107,6 +107,7 @@ Documentation)
test -n "$ALREADY_HAVE_ASCIIDOCTOR" ||
sudo gem install --version 1.5.8 asciidoctor
+ sudo gem install concurrent-ruby
;;
esac
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index 69917d7b845..f99a69ae1b7 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -56,14 +56,11 @@ txt_to_synopsis () {
fi &&
b2t="$(builtin_to_txt "$builtin")" &&
sed -n \
- -e '/^\[verse\]$/,/^$/ {
+ -E '/^\[(verse|synopsis)\]$/,/^$/ {
/^$/d;
- /^\[verse\]$/d;
- s/_//g;
- s/++//g;
- s/`//g;
- s/{litdd}/--/g;
- s/'\''\(git[ a-z-]*\)'\''/\1/g;
+ /^\[(verse|synopsis)\]$/d;
+ s/\{litdd\}/--/g;
+ s/'\''(git[ a-z-]*)'\''/\1/g;
p;
}' \
--
gitgitgadget
^ permalink raw reply related [flat|nested] 45+ messages in thread* [PATCH v4 2/3] doc: update the guidelines to reflect the current formatting rules
2024-09-05 21:52 ` [PATCH v4 " Jean-Noël Avila via GitGitGadget
2024-09-05 21:52 ` [PATCH v4 1/3] doc: introduce a synopsis typesetting Jean-Noël Avila via GitGitGadget
@ 2024-09-05 21:52 ` Jean-Noël Avila via GitGitGadget
2024-09-05 21:52 ` [PATCH v4 3/3] doc: apply synopsis simplification on git-clone and git-init Jean-Noël Avila via GitGitGadget
` (2 subsequent siblings)
4 siblings, 0 replies; 45+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2024-09-05 21:52 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Jean-Noël Avila, Jean-Noël Avila
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/CodingGuidelines | 58 ++++++++++++++++++----------------
1 file changed, 30 insertions(+), 28 deletions(-)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index ccaea39752c..13cbcf1d7a5 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -820,78 +820,80 @@ Markup:
_<new-branch-name>_
_<template-directory>_
- A placeholder is not enclosed in backticks, as it is not a literal.
-
When needed, use a distinctive identifier for placeholders, usually
made of a qualification and a type:
_<git-dir>_
_<key-id>_
- When literal and placeholders are mixed, each markup is applied for
- each sub-entity. If they are stuck, a special markup, called
- unconstrained formatting is required.
- Unconstrained formating for placeholders is __<like-this>__
- Unconstrained formatting for literal formatting is ++like this++
- `--jobs` _<n>_
- ++--sort=++__<key>__
- __<directory>__++/.git++
- ++remote.++__<name>__++.mirror++
+ Git's Asciidoc processor has been tailored to treat backticked text
+ as complex synopsis. When literal and placeholders are mixed, you can
+ use the backtick notation which will take care of correctly typesetting
+ the content.
+ `--jobs <n>`
+ `--sort=<key>`
+ `<directory>/.git`
+ `remote.<name>.mirror`
+ `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
- caveat: ++ unconstrained format is not verbatim and may expand
- content. Use Asciidoc escapes inside them.
+As a side effect, backquoted placeholders are correctly typeset, but
+this style is not recommended.
Synopsis Syntax
- Syntax grammar is formatted neither as literal nor as placeholder.
+ The synopsis (a paragraph with [synopsis] attribute) is automatically
+ formatted by the toolchain and does not need typesetting.
A few commented examples follow to provide reference when writing or
modifying command usage strings and synopsis sections in the manual
pages:
Possibility of multiple occurrences is indicated by three dots:
- _<file>_...
+ <file>...
(One or more of <file>.)
Optional parts are enclosed in square brackets:
- [_<file>_...]
+ [<file>...]
(Zero or more of <file>.)
- ++--exec-path++[++=++__<path>__]
+ An optional parameter needs to be typeset with unconstrained pairs
+ [<repository>]
+
+ --exec-path[=<path>]
(Option with an optional argument. Note that the "=" is inside the
brackets.)
- [_<patch>_...]
+ [<patch>...]
(Zero or more of <patch>. Note that the dots are inside, not
outside the brackets.)
Multiple alternatives are indicated with vertical bars:
- [`-q` | `--quiet`]
- [`--utf8` | `--no-utf8`]
+ [-q | --quiet]
+ [--utf8 | --no-utf8]
Use spacing around "|" token(s), but not immediately after opening or
before closing a [] or () pair:
- Do: [`-q` | `--quiet`]
- Don't: [`-q`|`--quiet`]
+ Do: [-q | --quiet]
+ Don't: [-q|--quiet]
Don't use spacing around "|" tokens when they're used to separate the
alternate arguments of an option:
- Do: ++--track++[++=++(`direct`|`inherit`)]`
- Don't: ++--track++[++=++(`direct` | `inherit`)]
+ Do: --track[=(direct|inherit)]
+ Don't: --track[=(direct | inherit)]
Parentheses are used for grouping:
- [(_<rev>_ | _<range>_)...]
+ [(<rev>|<range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
it clear that "..." pertains to both <rev> and <range>.)
- [(`-p` _<parent>_)...]
+ [(-p <parent>)...]
(Any number of option -p, each with one <parent> argument.)
- `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
+ git remote set-head <name> (-a|-d|<branch>)
(One and only one of "-a", "-d" or "<branch>" _must_ (no square
brackets) be provided.)
And a somewhat more contrived example:
- `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
+ --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
Here "=" is outside the brackets, because "--diff-filter=" is a
valid usage. "*" has its own pair of brackets, because it can
(optionally) be specified only when one or more of the letters is
--
gitgitgadget
^ permalink raw reply related [flat|nested] 45+ messages in thread* [PATCH v4 3/3] doc: apply synopsis simplification on git-clone and git-init
2024-09-05 21:52 ` [PATCH v4 " Jean-Noël Avila via GitGitGadget
2024-09-05 21:52 ` [PATCH v4 1/3] doc: introduce a synopsis typesetting Jean-Noël Avila via GitGitGadget
2024-09-05 21:52 ` [PATCH v4 2/3] doc: update the guidelines to reflect the current formatting rules Jean-Noël Avila via GitGitGadget
@ 2024-09-05 21:52 ` Jean-Noël Avila via GitGitGadget
2024-09-13 18:15 ` [PATCH v4 0/3] doc: introducing synopsis para Junio C Hamano
2024-09-24 7:08 ` [PATCH v5 " Jean-Noël Avila via GitGitGadget
4 siblings, 0 replies; 45+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2024-09-05 21:52 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Jean-Noël Avila, Jean-Noël Avila
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
With the new synopsis formatting backend, no special asciidoc markup
is needed.
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/git-clone.txt | 78 ++++++++++++++++++-------------------
Documentation/git-init.txt | 35 +++++++----------
Documentation/urls.txt | 26 ++++++-------
3 files changed, 67 insertions(+), 72 deletions(-)
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 8e925db7e9c..9c13f847da3 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory
SYNOPSIS
--------
-[verse]
-`git clone` [++--template=++__<template-directory>__]
- [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]
- [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]
- [`--dissociate`] [`--separate-git-dir` _<git-dir>_]
- [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]
- [++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++]
- [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]
- [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_
- [_<directory>_]
+[synopsis]
+git clone [--template=<template-directory>]
+ [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
+ [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
+ [--dissociate] [--separate-git-dir <git-dir>]
+ [--depth <depth>] [--[no-]single-branch] [--no-tags]
+ [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
+ [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
+ [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
+ [<directory>]
DESCRIPTION
-----------
@@ -52,7 +52,7 @@ OPTIONS
to save space when possible.
+
If the repository is specified as a local path (e.g., `/path/to/repo`),
-this is the default, and --local is essentially a no-op. If the
+this is the default, and `--local` is essentially a no-op. If the
repository is specified as a URL, then this flag is ignored (and we
never use the local optimizations). Specifying `--no-local` will
override the default when `/path/to/repo` is given, using the regular
@@ -64,8 +64,8 @@ prevent the unintentional copying of files by dereferencing the symbolic
links.
+
*NOTE*: this operation can race with concurrent modification to the
-source repository, similar to running `cp -r src dst` while modifying
-`src`.
+source repository, similar to running `cp -r <src> <dst>` while modifying
+_<src>_.
`--no-hardlinks`::
Force the cloning process from a repository on a local
@@ -101,7 +101,7 @@ If you want to break the dependency of a repository cloned with `--shared` on
its source repository, you can simply run `git repack -a` to copy all
objects from the source repository into a pack in the cloned repository.
-`--reference`[`-if-able`] _<repository>_::
+`--reference[-if-able] <repository>`::
If the reference _<repository>_ is on the local machine,
automatically setup `.git/objects/info/alternates` to
obtain objects from the reference _<repository>_. Using
@@ -142,17 +142,17 @@ objects from the source repository into a pack in the cloned repository.
is specified. This flag forces progress status even if the
standard error stream is not directed to a terminal.
-++--server-option=++__<option>__::
+`--server-option=<option>`::
Transmit the given string to the server when communicating using
protocol version 2. The given string must not contain a NUL or LF
character. The server's handling of server options, including
unknown ones, is server-specific.
- When multiple ++--server-option=++__<option>__ are given, they are all
+ When multiple `--server-option=<option>` are given, they are all
sent to the other side in the order listed on the command line.
`-n`::
`--no-checkout`::
- No checkout of HEAD is performed after the clone is complete.
+ No checkout of `HEAD` is performed after the clone is complete.
`--`[`no-`]`reject-shallow`::
Fail if the source repository is a shallow repository.
@@ -162,7 +162,7 @@ objects from the source repository into a pack in the cloned repository.
`--bare`::
Make a 'bare' Git repository. That is, instead of
creating _<directory>_ and placing the administrative
- files in _<directory>_`/.git`, make the _<directory>_
+ files in `<directory>/.git`, make the _<directory>_
itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
because there is nowhere to check out the working tree.
Also the branch heads at the remote are copied directly
@@ -177,13 +177,13 @@ objects from the source repository into a pack in the cloned repository.
linkgit:git-sparse-checkout[1] command can be used to grow the
working directory as needed.
-++--filter=++__<filter-spec>__::
+`--filter=<filter-spec>`::
Use the partial clone feature and request that the server sends
a subset of reachable objects according to a given object filter.
When using `--filter`, the supplied _<filter-spec>_ is used for
the partial clone filter. For example, `--filter=blob:none` will
filter out all blobs (file contents) until needed by Git. Also,
- ++--filter=blob:limit=++__<size>__ will filter out all blobs of size
+ `--filter=blob:limit=<size>` will filter out all blobs of size
at least _<size>_. For more details on filter specifications, see
the `--filter` option in linkgit:git-rev-list[1].
@@ -208,11 +208,11 @@ objects from the source repository into a pack in the cloned repository.
`-b` _<name>_::
`--branch` _<name>_::
- Instead of pointing the newly created HEAD to the branch pointed
- to by the cloned repository's HEAD, point to _<name>_ branch
+ Instead of pointing the newly created `HEAD` to the branch pointed
+ to by the cloned repository's `HEAD`, point to _<name>_ branch
instead. In a non-bare repository, this is the branch that will
be checked out.
- `--branch` can also take tags and detaches the HEAD at that commit
+ `--branch` can also take tags and detaches the `HEAD` at that commit
in the resulting repository.
`-u` _<upload-pack>_::
@@ -221,12 +221,12 @@ objects from the source repository into a pack in the cloned repository.
via ssh, this specifies a non-default path for the command
run on the other end.
-++--template=++__<template-directory>__::
+`--template=<template-directory>`::
Specify the directory from which templates will be used;
(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
-`-c` __<key>__++=++__<value>__::
-`--config` __<key>__++=++__<value>__::
+`-c` `<key>=<value>`::
+`--config` `<key>=<value>`::
Set a configuration variable in the newly-created repository;
this takes effect immediately after the repository is
initialized, but before the remote history is fetched or any
@@ -239,25 +239,25 @@ objects from the source repository into a pack in the cloned repository.
Due to limitations of the current implementation, some configuration
variables do not take effect until after the initial fetch and checkout.
Configuration variables known to not take effect are:
-++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++. Use the
+`remote.<name>.mirror` and `remote.<name>.tagOpt`. Use the
corresponding `--mirror` and `--no-tags` options instead.
-`--depth` _<depth>_::
+`--depth <depth>`::
Create a 'shallow' clone with a history truncated to the
specified number of commits. Implies `--single-branch` unless
`--no-single-branch` is given to fetch the histories near the
tips of all branches. If you want to clone submodules shallowly,
also pass `--shallow-submodules`.
-++--shallow-since=++__<date>__::
+`--shallow-since=<date>`::
Create a shallow clone with a history after the specified time.
-++--shallow-exclude=++__<revision>__::
+`--shallow-exclude=<revision>`::
Create a shallow clone with a history, excluding commits
reachable from a specified remote branch or tag. This option
can be specified multiple times.
-`--`[`no-`]`single-branch`::
+`--[no-]single-branch`::
Clone only the history leading to the tip of a single branch,
either specified by the `--branch` option or the primary
branch remote's `HEAD` points at.
@@ -279,13 +279,13 @@ maintain a branch with no references other than a single cloned
branch. This is useful e.g. to maintain minimal clones of the default
branch of some repository for search indexing.
-`--recurse-submodules`[`=`{empty}__<pathspec>__]::
+`--recurse-submodules[=<pathspec>]`::
After the clone is created, initialize and clone submodules
- within based on the provided _<pathspec>_. If no _=<pathspec>_ is
+ within based on the provided _<pathspec>_. If no `=<pathspec>` is
provided, all submodules are initialized and cloned.
This option can be given multiple times for pathspecs consisting
of multiple entries. The resulting clone has `submodule.active` set to
- the provided pathspec, or "." (meaning all submodules) if no
+ the provided pathspec, or "`.`" (meaning all submodules) if no
pathspec is provided.
+
Submodules are initialized and cloned using their default settings. This is
@@ -295,23 +295,23 @@ the clone is finished. This option is ignored if the cloned repository does
not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
or `--mirror` is given)
-`--`[`no-`]`shallow-submodules`::
+`--[no-]shallow-submodules`::
All submodules which are cloned will be shallow with a depth of 1.
-`--`[`no-`]`remote-submodules`::
+`--[no-]remote-submodules`::
All submodules which are cloned will use the status of the submodule's
remote-tracking branch to update the submodule, rather than the
superproject's recorded SHA-1. Equivalent to passing `--remote` to
`git submodule update`.
-`--separate-git-dir=`{empty}__<git-dir>__::
+`--separate-git-dir=<git-dir>`::
Instead of placing the cloned repository where it is supposed
to be, place the cloned repository at the specified directory,
then make a filesystem-agnostic Git symbolic link to there.
The result is Git repository can be separated from working
tree.
-`--ref-format=`{empty}__<ref-format>__::
+`--ref-format=<ref-format>`::
Specify the given ref storage format for the repository. The valid values are:
+
@@ -334,7 +334,7 @@ _<directory>_::
for `host.xz:foo/.git`). Cloning into an existing directory
is only allowed if the directory is empty.
-`--bundle-uri=`{empty}__<uri>__::
+`--bundle-uri=<uri>`::
Before fetching from the remote, fetch a bundle from the given
_<uri>_ and unbundle the data into the local repository. The refs
in the bundle will be stored under the hidden `refs/bundle/*`
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index daff93bd164..315f7f7530c 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one
SYNOPSIS
--------
-[verse]
-`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]
- [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]
- [++--ref-format=++__<format>__]
- [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]
- [++--shared++[++=++__<permissions>__]] [_<directory>_]
+[synopsis]
+git init [-q | --quiet] [--bare] [--template=<template-directory>]
+ [--separate-git-dir <git-dir>] [--object-format=<format>]
+ [--ref-format=<format>]
+ [-b <branch-name> | --initial-branch=<branch-name>]
+ [--shared[=<permissions>]] [<directory>]
DESCRIPTION
@@ -25,11 +25,11 @@ directory with subdirectories for `objects`, `refs/heads`,
commits will be created (see the `--initial-branch` option below
for its name).
-If the `$GIT_DIR` environment variable is set then it specifies a path
+If the `GIT_DIR` environment variable is set then it specifies a path
to use instead of `./.git` for the base of the repository.
If the object storage directory is specified via the
-`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
+`GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
are created underneath; otherwise, the default `$GIT_DIR/objects`
directory is used.
@@ -51,26 +51,22 @@ Only print error and warning messages; all other output will be suppressed.
Create a bare repository. If `GIT_DIR` environment is not set, it is set to the
current working directory.
-++--object-format=++__<format>__::
-
+`--object-format=<format>`::
Specify the given object _<format>_ (hash algorithm) for the repository. The valid
values are `sha1` and (if enabled) `sha256`. `sha1` is the default.
+
include::object-format-disclaimer.txt[]
-++--ref-format=++__<format>__::
-
+`--ref-format=<format>`::
Specify the given ref storage _<format>_ for the repository. The valid values are:
+
include::ref-storage-format.txt[]
-++--template=++__<template-directory>__::
-
+`--template=<template-directory>`::
Specify the directory from which templates will be used. (See the "TEMPLATE
DIRECTORY" section below.)
-++--separate-git-dir=++__<git-dir>__::
-
+`--separate-git-dir=<git-dir>`::
Instead of initializing the repository as a directory to either `$GIT_DIR` or
`./.git/`, create a text file there containing the path to the actual
repository. This file acts as a filesystem-agnostic Git symbolic link to the
@@ -78,15 +74,14 @@ repository.
+
If this is a reinitialization, the repository will be moved to the specified path.
-`-b` _<branch-name>_::
-++--initial-branch=++__<branch-name>__::
-
+`-b <branch-name>`::
+`--initial-branch=<branch-name>`::
Use _<branch-name>_ for the initial branch in the newly created
repository. If not specified, fall back to the default name (currently
`master`, but this is subject to change in the future; the name can be
customized via the `init.defaultBranch` configuration variable).
-++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::
+`--shared[=(false|true|umask|group|all|world|everybody|<perm>)]`::
Specify that the Git repository is to be shared amongst several users. This
allows users belonging to the same group to push into that
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 7cec85aef17..9c871e716a1 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -10,19 +10,19 @@ Git supports ssh, git, http, and https protocols (in addition, ftp
and ftps can be used for fetching, but this is inefficient and
deprecated; do not use them).
-The native transport (i.e. git:// URL) does no authentication and
+The native transport (i.e. `git://` URL) does no authentication and
should be used with caution on unsecured networks.
The following syntaxes may be used with them:
-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
+- `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
+- `git://<host>[:<port>]/<path-to-git-repo>`
+- `http[s]://<host>[:<port>]/<path-to-git-repo>`
+- `ftp[s]://<host>[:<port>]/<path-to-git-repo>`
An alternative scp-like syntax may also be used with the ssh protocol:
-- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__
+- `[<user>@]<host>:/<path-to-git-repo>`
This syntax is only recognized if there are no slashes before the
first colon. This helps differentiate a local path that contains a
@@ -30,17 +30,17 @@ colon. For example the local path `foo:bar` could be specified as an
absolute path or `./foo:bar` to avoid being misinterpreted as an ssh
url.
-The ssh and git protocols additionally support ++~++__<username>__ expansion:
+The ssh and git protocols additionally support `~<username>` expansion:
-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__
+- `ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>`
+- `git://<host>[:<port>]/~<user>/<path-to-git-repo>`
+- `[<user>@]<host>:~<user>/<path-to-git-repo>`
For local repositories, also supported by Git natively, the following
syntaxes may be used:
- `/path/to/repo.git/`
-- ++file:///path/to/repo.git/++
+- `file:///path/to/repo.git/`
ifndef::git-clone[]
These two syntaxes are mostly equivalent, except when cloning, when
@@ -57,11 +57,11 @@ endif::git-clone[]
accept a suitable bundle file. See linkgit:git-bundle[1].
When Git doesn't know how to handle a certain transport protocol, it
-attempts to use the `remote-`{empty}__<transport>__ remote helper, if one
+attempts to use the `remote-<transport>` remote helper, if one
exists. To explicitly request a remote helper, the following syntax
may be used:
-- _<transport>_::__<address>__
+- `<transport>::<address>`
where _<address>_ may be a path, a server and path, or an arbitrary
URL-like string recognized by the specific remote helper being
--
gitgitgadget
^ permalink raw reply related [flat|nested] 45+ messages in thread* Re: [PATCH v4 0/3] doc: introducing synopsis para
2024-09-05 21:52 ` [PATCH v4 " Jean-Noël Avila via GitGitGadget
` (2 preceding siblings ...)
2024-09-05 21:52 ` [PATCH v4 3/3] doc: apply synopsis simplification on git-clone and git-init Jean-Noël Avila via GitGitGadget
@ 2024-09-13 18:15 ` Junio C Hamano
2024-09-20 23:14 ` Josh Steadmon
2024-09-24 7:08 ` [PATCH v5 " Jean-Noël Avila via GitGitGadget
4 siblings, 1 reply; 45+ messages in thread
From: Junio C Hamano @ 2024-09-13 18:15 UTC (permalink / raw)
To: Jean-Noël Avila via GitGitGadget
Cc: git, Eric Sunshine, Jean-Noël Avila
"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> In the continuation of the simplification of manpage editing, the synopsis
> processing that was developed for synopsis paragraph style is also applied
> to all inline backquoted texts.
>
> Refining the magic regexp took more time than expected, but this one should
> really enhance writers'experience. I had to fight a bit more with
> asciidoctor, due to discrepancies between version 2.0 on my laptop and the
> 1.5.6 used by Github actions.
>
> The git-init and git-clone manpages are converted to this new system.
The fact that such a "magic" processing will hide the gory details
from those whose primary interest is to describe the commands and
their options cuts both ways. While I can understand that purists
would find it ugly, as `backticks` is now much more than a mark-up
that means "this text is typeset in monospace", it is a very welcome
thing for developers around here, who just want to write their
document in a way even whose source is readable without having to
worry about suh gory details. Maybe this gets popular enough after
other projects notice what you did to AsciiDoctor, love it, adopt
it, and eventually it feeds back to improve AsciiDoctor proper ;-).
So, unless there are objections and people want to discuss it further,
I'll mark the topic for 'next' soonish.
Thanks.
^ permalink raw reply [flat|nested] 45+ messages in thread* Re: [PATCH v4 0/3] doc: introducing synopsis para
2024-09-13 18:15 ` [PATCH v4 0/3] doc: introducing synopsis para Junio C Hamano
@ 2024-09-20 23:14 ` Josh Steadmon
2024-09-21 1:38 ` Junio C Hamano
2024-09-21 6:19 ` Junio C Hamano
0 siblings, 2 replies; 45+ messages in thread
From: Josh Steadmon @ 2024-09-20 23:14 UTC (permalink / raw)
To: Junio C Hamano
Cc: Jean-Noël Avila via GitGitGadget, git, Eric Sunshine,
Jean-Noël Avila
On 2024.09.13 11:15, Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > In the continuation of the simplification of manpage editing, the synopsis
> > processing that was developed for synopsis paragraph style is also applied
> > to all inline backquoted texts.
> >
> > Refining the magic regexp took more time than expected, but this one should
> > really enhance writers'experience. I had to fight a bit more with
> > asciidoctor, due to discrepancies between version 2.0 on my laptop and the
> > 1.5.6 used by Github actions.
> >
> > The git-init and git-clone manpages are converted to this new system.
>
> The fact that such a "magic" processing will hide the gory details
> from those whose primary interest is to describe the commands and
> their options cuts both ways. While I can understand that purists
> would find it ugly, as `backticks` is now much more than a mark-up
> that means "this text is typeset in monospace", it is a very welcome
> thing for developers around here, who just want to write their
> document in a way even whose source is readable without having to
> worry about suh gory details. Maybe this gets popular enough after
> other projects notice what you did to AsciiDoctor, love it, adopt
> it, and eventually it feeds back to improve AsciiDoctor proper ;-).
>
> So, unless there are objections and people want to discuss it further,
> I'll mark the topic for 'next' soonish.
>
> Thanks.
>
This still breaks on MacOS, as `sed` doesn't understand the '-E' option
there.
^ permalink raw reply [flat|nested] 45+ messages in thread
* Re: [PATCH v4 0/3] doc: introducing synopsis para
2024-09-20 23:14 ` Josh Steadmon
@ 2024-09-21 1:38 ` Junio C Hamano
2024-09-21 6:19 ` Junio C Hamano
1 sibling, 0 replies; 45+ messages in thread
From: Junio C Hamano @ 2024-09-21 1:38 UTC (permalink / raw)
To: Josh Steadmon
Cc: Jean-Noël Avila via GitGitGadget, git, Eric Sunshine,
Jean-Noël Avila
Josh Steadmon <steadmon@google.com> writes:
>> So, unless there are objections and people want to discuss it further,
>> I'll mark the topic for 'next' soonish.
>>
>> Thanks.
>>
>
> This still breaks on MacOS, as `sed` doesn't understand the '-E' option
> there.
Thanks for a report.
What is sad is that we are seeing this after the topic gets very
close to 'master' (it has been in 'next' already for a few days).
Perhaps nobody builds documentation on macOS, in which case the
breakage may be totally acceptable? Is that the message we are
hearing from mac based developers?
Grumpy...
^ permalink raw reply [flat|nested] 45+ messages in thread
* Re: [PATCH v4 0/3] doc: introducing synopsis para
2024-09-20 23:14 ` Josh Steadmon
2024-09-21 1:38 ` Junio C Hamano
@ 2024-09-21 6:19 ` Junio C Hamano
2024-09-21 6:23 ` Junio C Hamano
1 sibling, 1 reply; 45+ messages in thread
From: Junio C Hamano @ 2024-09-21 6:19 UTC (permalink / raw)
To: Josh Steadmon
Cc: Jean-Noël Avila via GitGitGadget, git, Eric Sunshine,
Jean-Noël Avila
Josh Steadmon <steadmon@google.com> writes:
> This still breaks on MacOS, as `sed` doesn't understand the '-E' option
> there.
Can you try to see t6030 also breaks due to lack of ERE in the same
environment? It seems it uses "sed -E", so it should fail to find
what it is trying to.
Thanks.
^ permalink raw reply [flat|nested] 45+ messages in thread
* Re: [PATCH v4 0/3] doc: introducing synopsis para
2024-09-21 6:19 ` Junio C Hamano
@ 2024-09-21 6:23 ` Junio C Hamano
2024-09-21 6:54 ` Chris Torek
0 siblings, 1 reply; 45+ messages in thread
From: Junio C Hamano @ 2024-09-21 6:23 UTC (permalink / raw)
To: Josh Steadmon
Cc: Jean-Noël Avila via GitGitGadget, git, Eric Sunshine,
Jean-Noël Avila
Junio C Hamano <gitster@pobox.com> writes:
> Josh Steadmon <steadmon@google.com> writes:
>
>> This still breaks on MacOS, as `sed` doesn't understand the '-E' option
>> there.
>
> Can you try to see t6030 also breaks due to lack of ERE in the same
> environment? It seems it uses "sed -E", so it should fail to find
> what it is trying to.
>
> Thanks.
The reason why I am curious is because https://ss64.com/mac/sed.html
claims that -E works.
Earlier I wrote somewhere whatever problem it is it would be shared
with BSD implementation of sed. But apparently BSD's sed also works
with the -E option. https://man.freebsd.org/cgi/man.cgi?sed(1)
So, I dunno. Perhaps it is not -E but some specific construct used
in the pattern?
^ permalink raw reply [flat|nested] 45+ messages in thread
* Re: [PATCH v4 0/3] doc: introducing synopsis para
2024-09-21 6:23 ` Junio C Hamano
@ 2024-09-21 6:54 ` Chris Torek
2024-09-23 16:38 ` Junio C Hamano
0 siblings, 1 reply; 45+ messages in thread
From: Chris Torek @ 2024-09-21 6:54 UTC (permalink / raw)
To: Junio C Hamano
Cc: Josh Steadmon, Jean-Noël Avila via GitGitGadget, git,
Eric Sunshine, Jean-Noël Avila
On Fri, Sep 20, 2024 at 11:24 PM Junio C Hamano <gitster@pobox.com> wrote:
> The reason why I am curious is because https://ss64.com/mac/sed.html
> claims that -E works.
It does for me, on my Mac, which is deliberately behind current: I am
still on Big Sur.
Chris
^ permalink raw reply [flat|nested] 45+ messages in thread
* Re: [PATCH v4 0/3] doc: introducing synopsis para
2024-09-21 6:54 ` Chris Torek
@ 2024-09-23 16:38 ` Junio C Hamano
[not found] ` <CAPig+cQgw8xf5bQaUEW=qvKQpnxrkiTrMsqa+VW9d_GX0au1sA@mail.gmail.com>
0 siblings, 1 reply; 45+ messages in thread
From: Junio C Hamano @ 2024-09-23 16:38 UTC (permalink / raw)
To: Josh Steadmon
Cc: Chris Torek, Jean-Noël Avila via GitGitGadget, git,
Eric Sunshine, Jean-Noël Avila
Chris Torek <chris.torek@gmail.com> writes:
> On Fri, Sep 20, 2024 at 11:24 PM Junio C Hamano <gitster@pobox.com> wrote:
>> The reason why I am curious is because https://ss64.com/mac/sed.html
>> claims that -E works.
>
> It does for me, on my Mac, which is deliberately behind current: I am
> still on Big Sur.
Thanks, Chris.
Josh, the topic has been cooking in 'next' long enough to graduate
to 'master' without anybody else complaining. Could you
double-check and if possible see what is different in your
environment from others?
I can hold the topic in 'next' longer but not forever without
progress. Help from macOS folks (if it is macOS specific issue)
is greatly appreciated.
Thanks.
^ permalink raw reply [flat|nested] 45+ messages in thread
* [PATCH v5 0/3] doc: introducing synopsis para
2024-09-05 21:52 ` [PATCH v4 " Jean-Noël Avila via GitGitGadget
` (3 preceding siblings ...)
2024-09-13 18:15 ` [PATCH v4 0/3] doc: introducing synopsis para Junio C Hamano
@ 2024-09-24 7:08 ` Jean-Noël Avila via GitGitGadget
2024-09-24 7:08 ` [PATCH v5 1/3] doc: introduce a synopsis typesetting Jean-Noël Avila via GitGitGadget
` (3 more replies)
4 siblings, 4 replies; 45+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2024-09-24 7:08 UTC (permalink / raw)
To: git; +Cc: Eric Sunshine, Josh Steadmon, Chris Torek, Jean-Noël Avila
In the continuation of the simplification of manpage editing, the synopsis
processing that was developed for synopsis paragraph style is also applied
to all inline backquoted texts.
Refining the magic regexp took more time than expected, but this one should
really enhance writers'experience. I had to fight a bit more with
asciidoctor, due to discrepancies between version 2.0 on my laptop and the
1.5.6 used by Github actions.
The git-init and git-clone manpages are converted to this new system.
Changes since V1:
* switch to sed for asciidoc filter and refine the regex for support under
macOS
Changes since V2:
* introduce the s macro to freely apply synopsis styling wherever needed,
without formatting hassle.
Changes since V3:
* replace s macro by direct processing of literal text at the level of
output processors.
Changes since V4:
* used BRE in sed filter
* rework the processing of three dots
Jean-Noël Avila (3):
doc: introduce a synopsis typesetting
doc: update the guidelines to reflect the current formatting rules
doc: apply synopsis simplification on git-clone and git-init
Documentation/CodingGuidelines | 58 +++++++++--------
Documentation/asciidoc.conf | 20 ++++++
Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++
Documentation/git-clone.txt | 78 +++++++++++-----------
Documentation/git-init.txt | 35 +++++-----
Documentation/urls.txt | 26 ++++----
ci/install-dependencies.sh | 1 +
t/t0450-txt-doc-vs-help.sh | 11 ++--
8 files changed, 209 insertions(+), 107 deletions(-)
base-commit: 2e7b89e038c0c888acf61f1b4ee5a43d4dd5e94c
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1766%2Fjnavila%2Fdoc_synopsis_para-v5
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1766/jnavila/doc_synopsis_para-v5
Pull-Request: https://github.com/gitgitgadget/git/pull/1766
Range-diff vs v4:
1: c09968d7ccb ! 1: 2946cc80314 doc: introduce a synopsis typesetting
@@ Documentation/asciidoc.conf: ifdef::backend-xhtml11[]
+ifdef::backend-docbook[]
+ifdef::doctype-manpage[]
+[paradef-default]
-+synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@,\/_^\$]+\.?+)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]+>!<emphasis>\\0</emphasis>!g'"
++synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|…\\)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]\\+>!<emphasis>\\0</emphasis>!g'"
+endif::doctype-manpage[]
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[paradef-default]
-+synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@,\/_^\$]+\.?)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]+>!<em>\\0</em>!g'"
++synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|…\\)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]\\+>!<em>\\0</em>!g'"
endif::backend-xhtml11[]
## Documentation/asciidoctor-extensions.rb ##
2: c48649ccd63 = 2: 06b8fff6a57 doc: update the guidelines to reflect the current formatting rules
3: 719188da711 = 3: a76998d6443 doc: apply synopsis simplification on git-clone and git-init
--
gitgitgadget
^ permalink raw reply [flat|nested] 45+ messages in thread* [PATCH v5 1/3] doc: introduce a synopsis typesetting
2024-09-24 7:08 ` [PATCH v5 " Jean-Noël Avila via GitGitGadget
@ 2024-09-24 7:08 ` Jean-Noël Avila via GitGitGadget
2024-09-24 7:08 ` [PATCH v5 2/3] doc: update the guidelines to reflect the current formatting rules Jean-Noël Avila via GitGitGadget
` (2 subsequent siblings)
3 siblings, 0 replies; 45+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2024-09-24 7:08 UTC (permalink / raw)
To: git
Cc: Eric Sunshine, Josh Steadmon, Chris Torek, Jean-Noël Avila,
Jean-Noël Avila
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
In order to follow the common manpage usage, the synopsis of the
commands needs to be heavily typeset. A first try was performed with
using native markup, but it turned out to make the document source
almost unreadable, difficult to write and prone to mistakes with
unwanted Asciidoc's role attributes.
In order to both simplify the writer's task and obtain a consistant
typesetting in the synopsis, a custom 'synopsis' paragraph type is
created and the processor for backticked text are modified. The
backends of asciidoc and asciidoctor take in charge to correctly add
the required typesetting.
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/asciidoc.conf | 20 ++++++
Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++
ci/install-dependencies.sh | 1 +
t/t0450-txt-doc-vs-help.sh | 11 ++--
4 files changed, 112 insertions(+), 7 deletions(-)
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 60f76f43eda..f6da6d1fbd2 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -28,6 +28,10 @@ ifdef::backend-docbook[]
{0#<citerefentry>}
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
{0#</citerefentry>}
+
+[literal-inlinemacro]
+{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
+
endif::backend-docbook[]
ifdef::backend-docbook[]
@@ -56,4 +60,20 @@ ifdef::backend-xhtml11[]
git-relative-html-prefix=
[linkgit-inlinemacro]
<a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
+
+[literal-inlinemacro]
+{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
+
+endif::backend-xhtml11[]
+
+ifdef::backend-docbook[]
+ifdef::doctype-manpage[]
+[paradef-default]
+synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|…\\)!\\1<literal>\\2</literal>!g;s!<[-a-zA-Z0-9.]\\+>!<emphasis>\\0</emphasis>!g'"
+endif::doctype-manpage[]
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[paradef-default]
+synopsis-style=template="verseparagraph",filter="sed 's!…\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|>\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|…\\)!\\1<code>\\2</code>!g;s!<[-a-zA-Z0-9.]\\+>!<em>\\0</em>!g'"
endif::backend-xhtml11[]
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index d906a008039..cb24480b63d 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -1,5 +1,7 @@
require 'asciidoctor'
require 'asciidoctor/extensions'
+require 'asciidoctor/converter/docbook5'
+require 'asciidoctor/converter/html5'
module Git
module Documentation
@@ -39,10 +41,95 @@ module Git
output
end
end
+
+ class SynopsisBlock < Asciidoctor::Extensions::BlockProcessor
+
+ use_dsl
+ named :synopsis
+ parse_content_as :simple
+
+ def process parent, reader, attrs
+ outlines = reader.lines.map do |l|
+ l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2')
+ .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}')
+ .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
+ .gsub(']', ']{empty}')
+ end
+ create_block parent, :verse, outlines, attrs
+ end
+ end
+
+ class GitDBConverter < Asciidoctor::Converter::DocBook5Converter
+
+ extend Asciidoctor::Converter::Config
+ register_for 'docbook5'
+
+ def convert_inline_quoted node
+ if (type = node.type) == :asciimath
+ # NOTE fop requires jeuclid to process mathml markup
+ asciimath_available? ? %(<inlineequation>#{(::AsciiMath.parse node.text).to_mathml 'mml:', 'xmlns:mml' => 'http://www.w3.org/1998/Math/MathML'}</inlineequation>) : %(<inlineequation><mathphrase><![CDATA[#{node.text}]]></mathphrase></inlineequation>)
+ elsif type == :latexmath
+ # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math
+ %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
+ elsif type == :monospaced
+ node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
+ .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
+ .gsub(/(<[-a-zA-Z0-9.]+>)/, '<emphasis>\1</emphasis>')
+ else
+ open, close, supports_phrase = QUOTE_TAGS[type]
+ text = node.text
+ if node.role
+ if supports_phrase
+ quoted_text = %(#{open}<phrase role="#{node.role}">#{text}</phrase>#{close})
+ else
+ quoted_text = %(#{open.chop} role="#{node.role}">#{text}#{close})
+ end
+ else
+ quoted_text = %(#{open}#{text}#{close})
+ end
+ node.id ? %(<anchor#{common_attributes node.id, nil, text}/>#{quoted_text}) : quoted_text
+ end
+ end
+ end
+
+ # register a html5 converter that takes in charge to convert monospaced text into Git style synopsis
+ class GitHTMLConverter < Asciidoctor::Converter::Html5Converter
+
+ extend Asciidoctor::Converter::Config
+ register_for 'html5'
+
+ def convert_inline_quoted node
+ if node.type == :monospaced
+ node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
+ .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
+ .gsub(/(<[-a-zA-Z0-9.]+>)/, '<em>\1</em>')
+
+ else
+ open, close, tag = QUOTE_TAGS[node.type]
+ if node.id
+ class_attr = node.role ? %( class="#{node.role}") : ''
+ if tag
+ %(#{open.chop} id="#{node.id}"#{class_attr}>#{node.text}#{close})
+ else
+ %(<span id="#{node.id}"#{class_attr}>#{open}#{node.text}#{close}</span>)
+ end
+ elsif node.role
+ if tag
+ %(#{open.chop} class="#{node.role}">#{node.text}#{close})
+ else
+ %(<span class="#{node.role}">#{open}#{node.text}#{close}</span>)
+ end
+ else
+ %(#{open}#{node.text}#{close})
+ end
+ end
+ end
+ end
end
end
Asciidoctor::Extensions.register do
inline_macro Git::Documentation::LinkGitProcessor, :linkgit
+ block Git::Documentation::SynopsisBlock
postprocessor Git::Documentation::DocumentPostProcessor
end
diff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh
index 4781cd20bb0..3e3ae39cbb1 100755
--- a/ci/install-dependencies.sh
+++ b/ci/install-dependencies.sh
@@ -107,6 +107,7 @@ Documentation)
test -n "$ALREADY_HAVE_ASCIIDOCTOR" ||
sudo gem install --version 1.5.8 asciidoctor
+ sudo gem install concurrent-ruby
;;
esac
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index 69917d7b845..f99a69ae1b7 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -56,14 +56,11 @@ txt_to_synopsis () {
fi &&
b2t="$(builtin_to_txt "$builtin")" &&
sed -n \
- -e '/^\[verse\]$/,/^$/ {
+ -E '/^\[(verse|synopsis)\]$/,/^$/ {
/^$/d;
- /^\[verse\]$/d;
- s/_//g;
- s/++//g;
- s/`//g;
- s/{litdd}/--/g;
- s/'\''\(git[ a-z-]*\)'\''/\1/g;
+ /^\[(verse|synopsis)\]$/d;
+ s/\{litdd\}/--/g;
+ s/'\''(git[ a-z-]*)'\''/\1/g;
p;
}' \
--
gitgitgadget
^ permalink raw reply related [flat|nested] 45+ messages in thread* [PATCH v5 2/3] doc: update the guidelines to reflect the current formatting rules
2024-09-24 7:08 ` [PATCH v5 " Jean-Noël Avila via GitGitGadget
2024-09-24 7:08 ` [PATCH v5 1/3] doc: introduce a synopsis typesetting Jean-Noël Avila via GitGitGadget
@ 2024-09-24 7:08 ` Jean-Noël Avila via GitGitGadget
2024-09-24 7:08 ` [PATCH v5 3/3] doc: apply synopsis simplification on git-clone and git-init Jean-Noël Avila via GitGitGadget
2024-09-24 17:16 ` [PATCH v5 0/3] doc: introducing synopsis para Junio C Hamano
3 siblings, 0 replies; 45+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2024-09-24 7:08 UTC (permalink / raw)
To: git
Cc: Eric Sunshine, Josh Steadmon, Chris Torek, Jean-Noël Avila,
Jean-Noël Avila
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/CodingGuidelines | 58 ++++++++++++++++++----------------
1 file changed, 30 insertions(+), 28 deletions(-)
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index ccaea39752c..13cbcf1d7a5 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -820,78 +820,80 @@ Markup:
_<new-branch-name>_
_<template-directory>_
- A placeholder is not enclosed in backticks, as it is not a literal.
-
When needed, use a distinctive identifier for placeholders, usually
made of a qualification and a type:
_<git-dir>_
_<key-id>_
- When literal and placeholders are mixed, each markup is applied for
- each sub-entity. If they are stuck, a special markup, called
- unconstrained formatting is required.
- Unconstrained formating for placeholders is __<like-this>__
- Unconstrained formatting for literal formatting is ++like this++
- `--jobs` _<n>_
- ++--sort=++__<key>__
- __<directory>__++/.git++
- ++remote.++__<name>__++.mirror++
+ Git's Asciidoc processor has been tailored to treat backticked text
+ as complex synopsis. When literal and placeholders are mixed, you can
+ use the backtick notation which will take care of correctly typesetting
+ the content.
+ `--jobs <n>`
+ `--sort=<key>`
+ `<directory>/.git`
+ `remote.<name>.mirror`
+ `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
- caveat: ++ unconstrained format is not verbatim and may expand
- content. Use Asciidoc escapes inside them.
+As a side effect, backquoted placeholders are correctly typeset, but
+this style is not recommended.
Synopsis Syntax
- Syntax grammar is formatted neither as literal nor as placeholder.
+ The synopsis (a paragraph with [synopsis] attribute) is automatically
+ formatted by the toolchain and does not need typesetting.
A few commented examples follow to provide reference when writing or
modifying command usage strings and synopsis sections in the manual
pages:
Possibility of multiple occurrences is indicated by three dots:
- _<file>_...
+ <file>...
(One or more of <file>.)
Optional parts are enclosed in square brackets:
- [_<file>_...]
+ [<file>...]
(Zero or more of <file>.)
- ++--exec-path++[++=++__<path>__]
+ An optional parameter needs to be typeset with unconstrained pairs
+ [<repository>]
+
+ --exec-path[=<path>]
(Option with an optional argument. Note that the "=" is inside the
brackets.)
- [_<patch>_...]
+ [<patch>...]
(Zero or more of <patch>. Note that the dots are inside, not
outside the brackets.)
Multiple alternatives are indicated with vertical bars:
- [`-q` | `--quiet`]
- [`--utf8` | `--no-utf8`]
+ [-q | --quiet]
+ [--utf8 | --no-utf8]
Use spacing around "|" token(s), but not immediately after opening or
before closing a [] or () pair:
- Do: [`-q` | `--quiet`]
- Don't: [`-q`|`--quiet`]
+ Do: [-q | --quiet]
+ Don't: [-q|--quiet]
Don't use spacing around "|" tokens when they're used to separate the
alternate arguments of an option:
- Do: ++--track++[++=++(`direct`|`inherit`)]`
- Don't: ++--track++[++=++(`direct` | `inherit`)]
+ Do: --track[=(direct|inherit)]
+ Don't: --track[=(direct | inherit)]
Parentheses are used for grouping:
- [(_<rev>_ | _<range>_)...]
+ [(<rev>|<range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
it clear that "..." pertains to both <rev> and <range>.)
- [(`-p` _<parent>_)...]
+ [(-p <parent>)...]
(Any number of option -p, each with one <parent> argument.)
- `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
+ git remote set-head <name> (-a|-d|<branch>)
(One and only one of "-a", "-d" or "<branch>" _must_ (no square
brackets) be provided.)
And a somewhat more contrived example:
- `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
+ --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
Here "=" is outside the brackets, because "--diff-filter=" is a
valid usage. "*" has its own pair of brackets, because it can
(optionally) be specified only when one or more of the letters is
--
gitgitgadget
^ permalink raw reply related [flat|nested] 45+ messages in thread* [PATCH v5 3/3] doc: apply synopsis simplification on git-clone and git-init
2024-09-24 7:08 ` [PATCH v5 " Jean-Noël Avila via GitGitGadget
2024-09-24 7:08 ` [PATCH v5 1/3] doc: introduce a synopsis typesetting Jean-Noël Avila via GitGitGadget
2024-09-24 7:08 ` [PATCH v5 2/3] doc: update the guidelines to reflect the current formatting rules Jean-Noël Avila via GitGitGadget
@ 2024-09-24 7:08 ` Jean-Noël Avila via GitGitGadget
2024-09-24 17:16 ` [PATCH v5 0/3] doc: introducing synopsis para Junio C Hamano
3 siblings, 0 replies; 45+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2024-09-24 7:08 UTC (permalink / raw)
To: git
Cc: Eric Sunshine, Josh Steadmon, Chris Torek, Jean-Noël Avila,
Jean-Noël Avila
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
With the new synopsis formatting backend, no special asciidoc markup
is needed.
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/git-clone.txt | 78 ++++++++++++++++++-------------------
Documentation/git-init.txt | 35 +++++++----------
Documentation/urls.txt | 26 ++++++-------
3 files changed, 67 insertions(+), 72 deletions(-)
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 8e925db7e9c..9c13f847da3 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory
SYNOPSIS
--------
-[verse]
-`git clone` [++--template=++__<template-directory>__]
- [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]
- [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]
- [`--dissociate`] [`--separate-git-dir` _<git-dir>_]
- [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]
- [++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++]
- [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]
- [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_
- [_<directory>_]
+[synopsis]
+git clone [--template=<template-directory>]
+ [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
+ [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
+ [--dissociate] [--separate-git-dir <git-dir>]
+ [--depth <depth>] [--[no-]single-branch] [--no-tags]
+ [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]
+ [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
+ [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
+ [<directory>]
DESCRIPTION
-----------
@@ -52,7 +52,7 @@ OPTIONS
to save space when possible.
+
If the repository is specified as a local path (e.g., `/path/to/repo`),
-this is the default, and --local is essentially a no-op. If the
+this is the default, and `--local` is essentially a no-op. If the
repository is specified as a URL, then this flag is ignored (and we
never use the local optimizations). Specifying `--no-local` will
override the default when `/path/to/repo` is given, using the regular
@@ -64,8 +64,8 @@ prevent the unintentional copying of files by dereferencing the symbolic
links.
+
*NOTE*: this operation can race with concurrent modification to the
-source repository, similar to running `cp -r src dst` while modifying
-`src`.
+source repository, similar to running `cp -r <src> <dst>` while modifying
+_<src>_.
`--no-hardlinks`::
Force the cloning process from a repository on a local
@@ -101,7 +101,7 @@ If you want to break the dependency of a repository cloned with `--shared` on
its source repository, you can simply run `git repack -a` to copy all
objects from the source repository into a pack in the cloned repository.
-`--reference`[`-if-able`] _<repository>_::
+`--reference[-if-able] <repository>`::
If the reference _<repository>_ is on the local machine,
automatically setup `.git/objects/info/alternates` to
obtain objects from the reference _<repository>_. Using
@@ -142,17 +142,17 @@ objects from the source repository into a pack in the cloned repository.
is specified. This flag forces progress status even if the
standard error stream is not directed to a terminal.
-++--server-option=++__<option>__::
+`--server-option=<option>`::
Transmit the given string to the server when communicating using
protocol version 2. The given string must not contain a NUL or LF
character. The server's handling of server options, including
unknown ones, is server-specific.
- When multiple ++--server-option=++__<option>__ are given, they are all
+ When multiple `--server-option=<option>` are given, they are all
sent to the other side in the order listed on the command line.
`-n`::
`--no-checkout`::
- No checkout of HEAD is performed after the clone is complete.
+ No checkout of `HEAD` is performed after the clone is complete.
`--`[`no-`]`reject-shallow`::
Fail if the source repository is a shallow repository.
@@ -162,7 +162,7 @@ objects from the source repository into a pack in the cloned repository.
`--bare`::
Make a 'bare' Git repository. That is, instead of
creating _<directory>_ and placing the administrative
- files in _<directory>_`/.git`, make the _<directory>_
+ files in `<directory>/.git`, make the _<directory>_
itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
because there is nowhere to check out the working tree.
Also the branch heads at the remote are copied directly
@@ -177,13 +177,13 @@ objects from the source repository into a pack in the cloned repository.
linkgit:git-sparse-checkout[1] command can be used to grow the
working directory as needed.
-++--filter=++__<filter-spec>__::
+`--filter=<filter-spec>`::
Use the partial clone feature and request that the server sends
a subset of reachable objects according to a given object filter.
When using `--filter`, the supplied _<filter-spec>_ is used for
the partial clone filter. For example, `--filter=blob:none` will
filter out all blobs (file contents) until needed by Git. Also,
- ++--filter=blob:limit=++__<size>__ will filter out all blobs of size
+ `--filter=blob:limit=<size>` will filter out all blobs of size
at least _<size>_. For more details on filter specifications, see
the `--filter` option in linkgit:git-rev-list[1].
@@ -208,11 +208,11 @@ objects from the source repository into a pack in the cloned repository.
`-b` _<name>_::
`--branch` _<name>_::
- Instead of pointing the newly created HEAD to the branch pointed
- to by the cloned repository's HEAD, point to _<name>_ branch
+ Instead of pointing the newly created `HEAD` to the branch pointed
+ to by the cloned repository's `HEAD`, point to _<name>_ branch
instead. In a non-bare repository, this is the branch that will
be checked out.
- `--branch` can also take tags and detaches the HEAD at that commit
+ `--branch` can also take tags and detaches the `HEAD` at that commit
in the resulting repository.
`-u` _<upload-pack>_::
@@ -221,12 +221,12 @@ objects from the source repository into a pack in the cloned repository.
via ssh, this specifies a non-default path for the command
run on the other end.
-++--template=++__<template-directory>__::
+`--template=<template-directory>`::
Specify the directory from which templates will be used;
(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
-`-c` __<key>__++=++__<value>__::
-`--config` __<key>__++=++__<value>__::
+`-c` `<key>=<value>`::
+`--config` `<key>=<value>`::
Set a configuration variable in the newly-created repository;
this takes effect immediately after the repository is
initialized, but before the remote history is fetched or any
@@ -239,25 +239,25 @@ objects from the source repository into a pack in the cloned repository.
Due to limitations of the current implementation, some configuration
variables do not take effect until after the initial fetch and checkout.
Configuration variables known to not take effect are:
-++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++. Use the
+`remote.<name>.mirror` and `remote.<name>.tagOpt`. Use the
corresponding `--mirror` and `--no-tags` options instead.
-`--depth` _<depth>_::
+`--depth <depth>`::
Create a 'shallow' clone with a history truncated to the
specified number of commits. Implies `--single-branch` unless
`--no-single-branch` is given to fetch the histories near the
tips of all branches. If you want to clone submodules shallowly,
also pass `--shallow-submodules`.
-++--shallow-since=++__<date>__::
+`--shallow-since=<date>`::
Create a shallow clone with a history after the specified time.
-++--shallow-exclude=++__<revision>__::
+`--shallow-exclude=<revision>`::
Create a shallow clone with a history, excluding commits
reachable from a specified remote branch or tag. This option
can be specified multiple times.
-`--`[`no-`]`single-branch`::
+`--[no-]single-branch`::
Clone only the history leading to the tip of a single branch,
either specified by the `--branch` option or the primary
branch remote's `HEAD` points at.
@@ -279,13 +279,13 @@ maintain a branch with no references other than a single cloned
branch. This is useful e.g. to maintain minimal clones of the default
branch of some repository for search indexing.
-`--recurse-submodules`[`=`{empty}__<pathspec>__]::
+`--recurse-submodules[=<pathspec>]`::
After the clone is created, initialize and clone submodules
- within based on the provided _<pathspec>_. If no _=<pathspec>_ is
+ within based on the provided _<pathspec>_. If no `=<pathspec>` is
provided, all submodules are initialized and cloned.
This option can be given multiple times for pathspecs consisting
of multiple entries. The resulting clone has `submodule.active` set to
- the provided pathspec, or "." (meaning all submodules) if no
+ the provided pathspec, or "`.`" (meaning all submodules) if no
pathspec is provided.
+
Submodules are initialized and cloned using their default settings. This is
@@ -295,23 +295,23 @@ the clone is finished. This option is ignored if the cloned repository does
not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
or `--mirror` is given)
-`--`[`no-`]`shallow-submodules`::
+`--[no-]shallow-submodules`::
All submodules which are cloned will be shallow with a depth of 1.
-`--`[`no-`]`remote-submodules`::
+`--[no-]remote-submodules`::
All submodules which are cloned will use the status of the submodule's
remote-tracking branch to update the submodule, rather than the
superproject's recorded SHA-1. Equivalent to passing `--remote` to
`git submodule update`.
-`--separate-git-dir=`{empty}__<git-dir>__::
+`--separate-git-dir=<git-dir>`::
Instead of placing the cloned repository where it is supposed
to be, place the cloned repository at the specified directory,
then make a filesystem-agnostic Git symbolic link to there.
The result is Git repository can be separated from working
tree.
-`--ref-format=`{empty}__<ref-format>__::
+`--ref-format=<ref-format>`::
Specify the given ref storage format for the repository. The valid values are:
+
@@ -334,7 +334,7 @@ _<directory>_::
for `host.xz:foo/.git`). Cloning into an existing directory
is only allowed if the directory is empty.
-`--bundle-uri=`{empty}__<uri>__::
+`--bundle-uri=<uri>`::
Before fetching from the remote, fetch a bundle from the given
_<uri>_ and unbundle the data into the local repository. The refs
in the bundle will be stored under the hidden `refs/bundle/*`
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index daff93bd164..315f7f7530c 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one
SYNOPSIS
--------
-[verse]
-`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]
- [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]
- [++--ref-format=++__<format>__]
- [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]
- [++--shared++[++=++__<permissions>__]] [_<directory>_]
+[synopsis]
+git init [-q | --quiet] [--bare] [--template=<template-directory>]
+ [--separate-git-dir <git-dir>] [--object-format=<format>]
+ [--ref-format=<format>]
+ [-b <branch-name> | --initial-branch=<branch-name>]
+ [--shared[=<permissions>]] [<directory>]
DESCRIPTION
@@ -25,11 +25,11 @@ directory with subdirectories for `objects`, `refs/heads`,
commits will be created (see the `--initial-branch` option below
for its name).
-If the `$GIT_DIR` environment variable is set then it specifies a path
+If the `GIT_DIR` environment variable is set then it specifies a path
to use instead of `./.git` for the base of the repository.
If the object storage directory is specified via the
-`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
+`GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
are created underneath; otherwise, the default `$GIT_DIR/objects`
directory is used.
@@ -51,26 +51,22 @@ Only print error and warning messages; all other output will be suppressed.
Create a bare repository. If `GIT_DIR` environment is not set, it is set to the
current working directory.
-++--object-format=++__<format>__::
-
+`--object-format=<format>`::
Specify the given object _<format>_ (hash algorithm) for the repository. The valid
values are `sha1` and (if enabled) `sha256`. `sha1` is the default.
+
include::object-format-disclaimer.txt[]
-++--ref-format=++__<format>__::
-
+`--ref-format=<format>`::
Specify the given ref storage _<format>_ for the repository. The valid values are:
+
include::ref-storage-format.txt[]
-++--template=++__<template-directory>__::
-
+`--template=<template-directory>`::
Specify the directory from which templates will be used. (See the "TEMPLATE
DIRECTORY" section below.)
-++--separate-git-dir=++__<git-dir>__::
-
+`--separate-git-dir=<git-dir>`::
Instead of initializing the repository as a directory to either `$GIT_DIR` or
`./.git/`, create a text file there containing the path to the actual
repository. This file acts as a filesystem-agnostic Git symbolic link to the
@@ -78,15 +74,14 @@ repository.
+
If this is a reinitialization, the repository will be moved to the specified path.
-`-b` _<branch-name>_::
-++--initial-branch=++__<branch-name>__::
-
+`-b <branch-name>`::
+`--initial-branch=<branch-name>`::
Use _<branch-name>_ for the initial branch in the newly created
repository. If not specified, fall back to the default name (currently
`master`, but this is subject to change in the future; the name can be
customized via the `init.defaultBranch` configuration variable).
-++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::
+`--shared[=(false|true|umask|group|all|world|everybody|<perm>)]`::
Specify that the Git repository is to be shared amongst several users. This
allows users belonging to the same group to push into that
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 7cec85aef17..9c871e716a1 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -10,19 +10,19 @@ Git supports ssh, git, http, and https protocols (in addition, ftp
and ftps can be used for fetching, but this is inefficient and
deprecated; do not use them).
-The native transport (i.e. git:// URL) does no authentication and
+The native transport (i.e. `git://` URL) does no authentication and
should be used with caution on unsecured networks.
The following syntaxes may be used with them:
-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
+- `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
+- `git://<host>[:<port>]/<path-to-git-repo>`
+- `http[s]://<host>[:<port>]/<path-to-git-repo>`
+- `ftp[s]://<host>[:<port>]/<path-to-git-repo>`
An alternative scp-like syntax may also be used with the ssh protocol:
-- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__
+- `[<user>@]<host>:/<path-to-git-repo>`
This syntax is only recognized if there are no slashes before the
first colon. This helps differentiate a local path that contains a
@@ -30,17 +30,17 @@ colon. For example the local path `foo:bar` could be specified as an
absolute path or `./foo:bar` to avoid being misinterpreted as an ssh
url.
-The ssh and git protocols additionally support ++~++__<username>__ expansion:
+The ssh and git protocols additionally support `~<username>` expansion:
-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__
+- `ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>`
+- `git://<host>[:<port>]/~<user>/<path-to-git-repo>`
+- `[<user>@]<host>:~<user>/<path-to-git-repo>`
For local repositories, also supported by Git natively, the following
syntaxes may be used:
- `/path/to/repo.git/`
-- ++file:///path/to/repo.git/++
+- `file:///path/to/repo.git/`
ifndef::git-clone[]
These two syntaxes are mostly equivalent, except when cloning, when
@@ -57,11 +57,11 @@ endif::git-clone[]
accept a suitable bundle file. See linkgit:git-bundle[1].
When Git doesn't know how to handle a certain transport protocol, it
-attempts to use the `remote-`{empty}__<transport>__ remote helper, if one
+attempts to use the `remote-<transport>` remote helper, if one
exists. To explicitly request a remote helper, the following syntax
may be used:
-- _<transport>_::__<address>__
+- `<transport>::<address>`
where _<address>_ may be a path, a server and path, or an arbitrary
URL-like string recognized by the specific remote helper being
--
gitgitgadget
^ permalink raw reply related [flat|nested] 45+ messages in thread* Re: [PATCH v5 0/3] doc: introducing synopsis para
2024-09-24 7:08 ` [PATCH v5 " Jean-Noël Avila via GitGitGadget
` (2 preceding siblings ...)
2024-09-24 7:08 ` [PATCH v5 3/3] doc: apply synopsis simplification on git-clone and git-init Jean-Noël Avila via GitGitGadget
@ 2024-09-24 17:16 ` Junio C Hamano
2024-09-24 19:30 ` Torsten Bögershausen
3 siblings, 1 reply; 45+ messages in thread
From: Junio C Hamano @ 2024-09-24 17:16 UTC (permalink / raw)
To: Josh Steadmon, Jean-Noël Avila via GitGitGadget
Cc: git, Eric Sunshine, Chris Torek, Jean-Noël Avila
"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> Changes since V4:
>
> * used BRE in sed filter
> * rework the processing of three dots
The topic has been deep in 'next' already, and I wasn't expecting a
wholesale replacement. But thanks for updating.
As the patches are more in the technology demonstration phase by
converting only a few pages and making sure other uses of `` outside
the synopsis section in unconverted pages are not broken, we can
declare that the three-patch series will not be in 2.47 and will
keep it in 'next'. So let me revert the merge of the previous one
out of 'next' and queue this one afresh to 'seen' to see how well it
works.
Josh (or whoever is taking over this week from him at Google), can
you see if the breakage you saw that stopped us merging the topic
before it causes us trouble on 'master' reproduces with this version
(either by running "make doc" on the topic branch by itself, or on
'seen' that merges the topic) in your environment that had trouble
with the previous round?
It would also be highly appreciated if other macOS users try "make
doc" and see the resulting git-init and git-clone documentation
pages are reasonable, both for the previous round that has been
cooking in 'next' and for this latest round. Inputs from folks on
more mainstream platforms with modern asciidoc/asciidoctor toolchain
would also help. The more people we have who look at how the new
way the synopsis section is written and how the resulting documents
get rendered, the more fairly we can assess the value of this topic.
Thanks.
^ permalink raw reply [flat|nested] 45+ messages in thread* Re: [PATCH v5 0/3] doc: introducing synopsis para
2024-09-24 17:16 ` [PATCH v5 0/3] doc: introducing synopsis para Junio C Hamano
@ 2024-09-24 19:30 ` Torsten Bögershausen
2024-09-24 20:33 ` Junio C Hamano
0 siblings, 1 reply; 45+ messages in thread
From: Torsten Bögershausen @ 2024-09-24 19:30 UTC (permalink / raw)
To: Junio C Hamano
Cc: Josh Steadmon, Jean-Noël Avila via GitGitGadget, git,
Eric Sunshine, Chris Torek, Jean-Noël Avila
On Tue, Sep 24, 2024 at 10:16:10AM -0700, Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > Changes since V4:
> >
> > * used BRE in sed filter
> > * rework the processing of three dots
>
> The topic has been deep in 'next' already, and I wasn't expecting a
> wholesale replacement. But thanks for updating.
>
> As the patches are more in the technology demonstration phase by
> converting only a few pages and making sure other uses of `` outside
> the synopsis section in unconverted pages are not broken, we can
> declare that the three-patch series will not be in 2.47 and will
> keep it in 'next'. So let me revert the merge of the previous one
> out of 'next' and queue this one afresh to 'seen' to see how well it
> works.
>
> Josh (or whoever is taking over this week from him at Google), can
> you see if the breakage you saw that stopped us merging the topic
> before it causes us trouble on 'master' reproduces with this version
> (either by running "make doc" on the topic branch by itself, or on
> 'seen' that merges the topic) in your environment that had trouble
> with the previous round?
>
> It would also be highly appreciated if other macOS users try "make
> doc" and see the resulting git-init and git-clone documentation
> pages are reasonable, both for the previous round that has been
> cooking in 'next' and for this latest round. Inputs from folks on
> more mainstream platforms with modern asciidoc/asciidoctor toolchain
> would also help. The more people we have who look at how the new
> way the synopsis section is written and how the resulting documents
> get rendered, the more fairly we can assess the value of this topic.
>
> Thanks.
>
Here a report from a MacOs user,
asciidoc --version
asciidoc 10.2.0
installed via macports.
No problems seen in the seen branch.
I diffed git-init.html from seen of today against both master and next,
some (minor) improvements (like GIT_OBJECT_DIRECTORY vs $GIT_OBJECT_DIRECTORY)
All in all it looks all sensible.
(and yes, `sed` understands -E)
^ permalink raw reply [flat|nested] 45+ messages in thread
* Re: [PATCH v5 0/3] doc: introducing synopsis para
2024-09-24 19:30 ` Torsten Bögershausen
@ 2024-09-24 20:33 ` Junio C Hamano
2024-10-02 21:41 ` Josh Steadmon
0 siblings, 1 reply; 45+ messages in thread
From: Junio C Hamano @ 2024-09-24 20:33 UTC (permalink / raw)
To: Torsten Bögershausen
Cc: Josh Steadmon, Jean-Noël Avila via GitGitGadget, git,
Eric Sunshine, Chris Torek, Jean-Noël Avila
Torsten Bögershausen <tboegi@web.de> writes:
> On Tue, Sep 24, 2024 at 10:16:10AM -0700, Junio C Hamano wrote:
>> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
>>
>> > Changes since V4:
>> >
>> > * used BRE in sed filter
>> > * rework the processing of three dots
>> ...
>> Josh (or whoever is taking over this week from him at Google), can
>> you see if the breakage you saw that stopped us merging the topic
>> before it causes us trouble on 'master' reproduces with this version
>> (either by running "make doc" on the topic branch by itself, or on
>> 'seen' that merges the topic) in your environment that had trouble
>> with the previous round?
>>
>> It would also be highly appreciated if other macOS users try "make
>> doc" and see the resulting git-init and git-clone documentation
>> pages are reasonable, both for the previous round that has been
>> cooking in 'next' and for this latest round. Inputs from folks on
>> more mainstream platforms with modern asciidoc/asciidoctor toolchain
>> would also help. The more people we have who look at how the new
>> way the synopsis section is written and how the resulting documents
>> get rendered, the more fairly we can assess the value of this topic.
>>
> Here a report from a MacOs user,
> asciidoc --version
> asciidoc 10.2.0
>
> installed via macports.
>
> No problems seen in the seen branch.
>
> I diffed git-init.html from seen of today against both master and next,
> some (minor) improvements (like GIT_OBJECT_DIRECTORY vs $GIT_OBJECT_DIRECTORY)
> All in all it looks all sensible.
> (and yes, `sed` understands -E)
Since I haven't pushed out the 'seen' branch with latest iteration,
your sucess report is about the previous iteration that Josh said
"still breaks on MacOS" [*]. The plot thickens...
Thanks.
[Reference]
* https://lore.kernel.org/git/4ww5v253vz2g4i3z2x3dmgkrot7mcn2qm6ckjcxbyky6yvrozy@mr5hnrsfj6sn/
^ permalink raw reply [flat|nested] 45+ messages in thread
* Re: [PATCH v5 0/3] doc: introducing synopsis para
2024-09-24 20:33 ` Junio C Hamano
@ 2024-10-02 21:41 ` Josh Steadmon
2024-10-02 22:43 ` Junio C Hamano
0 siblings, 1 reply; 45+ messages in thread
From: Josh Steadmon @ 2024-10-02 21:41 UTC (permalink / raw)
To: Junio C Hamano
Cc: Torsten Bögershausen, Jean-Noël Avila via GitGitGadget,
git, Eric Sunshine, Chris Torek, Jean-Noël Avila
On 2024.09.24 13:33, Junio C Hamano wrote:
> Torsten Bögershausen <tboegi@web.de> writes:
>
> > On Tue, Sep 24, 2024 at 10:16:10AM -0700, Junio C Hamano wrote:
> >> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> >>
> >> > Changes since V4:
> >> >
> >> > * used BRE in sed filter
> >> > * rework the processing of three dots
> >> ...
> >> Josh (or whoever is taking over this week from him at Google), can
> >> you see if the breakage you saw that stopped us merging the topic
> >> before it causes us trouble on 'master' reproduces with this version
> >> (either by running "make doc" on the topic branch by itself, or on
> >> 'seen' that merges the topic) in your environment that had trouble
> >> with the previous round?
> >>
> >> It would also be highly appreciated if other macOS users try "make
> >> doc" and see the resulting git-init and git-clone documentation
> >> pages are reasonable, both for the previous round that has been
> >> cooking in 'next' and for this latest round. Inputs from folks on
> >> more mainstream platforms with modern asciidoc/asciidoctor toolchain
> >> would also help. The more people we have who look at how the new
> >> way the synopsis section is written and how the resulting documents
> >> get rendered, the more fairly we can assess the value of this topic.
> >>
> > Here a report from a MacOs user,
> > asciidoc --version
> > asciidoc 10.2.0
> >
> > installed via macports.
> >
> > No problems seen in the seen branch.
> >
> > I diffed git-init.html from seen of today against both master and next,
> > some (minor) improvements (like GIT_OBJECT_DIRECTORY vs $GIT_OBJECT_DIRECTORY)
> > All in all it looks all sensible.
> > (and yes, `sed` understands -E)
>
> Since I haven't pushed out the 'seen' branch with latest iteration,
> your sucess report is about the previous iteration that Josh said
> "still breaks on MacOS" [*]. The plot thickens...
>
> Thanks.
>
>
> [Reference]
>
> * https://lore.kernel.org/git/4ww5v253vz2g4i3z2x3dmgkrot7mcn2qm6ckjcxbyky6yvrozy@mr5hnrsfj6sn/
I finally got the chance to test this version on $DAYJOB's build
infrastructure, and I verified that it works (I also got a much more
recent version of sed installed).
^ permalink raw reply [flat|nested] 45+ messages in thread
* Re: [PATCH v5 0/3] doc: introducing synopsis para
2024-10-02 21:41 ` Josh Steadmon
@ 2024-10-02 22:43 ` Junio C Hamano
0 siblings, 0 replies; 45+ messages in thread
From: Junio C Hamano @ 2024-10-02 22:43 UTC (permalink / raw)
To: Josh Steadmon
Cc: Torsten Bögershausen, Jean-Noël Avila via GitGitGadget,
git, Eric Sunshine, Chris Torek, Jean-Noël Avila
Josh Steadmon <steadmon@google.com> writes:
> I finally got the chance to test this version on $DAYJOB's build
> infrastructure, and I verified that it works (I also got a much more
> recent version of sed installed).
Thanks for a follow-up.
^ permalink raw reply [flat|nested] 45+ messages in thread