| Message ID | pull.1766.v2.git.1721855179.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | doc: introducing synopsis para | expand |
"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes: > Following several issues with the way the formatting of synopsis is done in > the manpages that were recently reworked, this patch series introduces the > processing of a new custom paragraph attribute 'synopsis'. The rendered result looks OK but the source being just like what we would write in plain text files without any extra mark-up makes it look quite nice. I wonder what we want to do with some oddballs, like git-shortlog that uses "|" not as an alternative but literally a pipe (i.e. "feed the output of this other command via a pipe to this command"), though. git log --pretty=short | git shortlog [<options>] There may be also some page that indicates "this command takes its input from its standard input" by using something like git cmd [--foo] [--bar] <input-file which we may need to think how to handle. The easiest way out may be to say "don't do these to indicate/force where the input comes from". I dunno. Thanks.
On Thursday, 25 July 2024 01:15:48 CEST Junio C Hamano wrote: > "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes: > > > Following several issues with the way the formatting of synopsis is done in > > the manpages that were recently reworked, this patch series introduces the > > processing of a new custom paragraph attribute 'synopsis'. > > The rendered result looks OK but the source being just like what we > would write in plain text files without any extra mark-up makes it > look quite nice. > > I wonder what we want to do with some oddballs, like git-shortlog > that uses "|" not as an alternative but literally a pipe (i.e. "feed > the output of this other command via a pipe to this command"), > though. > > git log --pretty=short | git shortlog [<options>] I must confess that while reviewing my patch, by switching all [verse] to [synopsis] , I looked at this line and understood the pipe as an alternative from the grammar, not as a shell pipe. I also noted a few spots where the grammar may be misinterpreted e.g. parenthesis in git-grep. In theory the typesetting should tell the keyword apart from the grammar, but for signs such as pipes and parenthesis the rendering does not change enough. > > There may be also some page that indicates "this command takes its > input from its standard input" by using something like > > git cmd [--foo] [--bar] <input-file > > which we may need to think how to handle. The easiest way out may > be to say "don't do these to indicate/force where the input comes > from". I dunno. > The form git cmd [--foo] [--bar] < <input-file> is completely acceptable , would render correctly and would remove the use of the pipe. The thing is that this pipe isn't even part of the command. It is just an example. Maybe it should not appear in the synopsis at all. For keyword signs that are already used in expressing the grammar, we could quote the sign to indicate that it is a keyword : "(" . Thanks
Jean-Noël AVILA <jn.avila@free.fr> writes: > The form > > git cmd [--foo] [--bar] < <input-file> > > is completely acceptable , would render correctly and would remove the use of > the pipe. Nice. I was afraid that it might be interpreted as a placeholder whose description is "<input-file" ;-) > The thing is that this pipe isn't even part of the command. It is > just an example. Maybe it should not appear in the synopsis at all. Historically the command was designed to read from "git log" as its upstream and nothing else, which was where that sample command in the synopsis originated, but it is unusual to spell out the upstream (or downstream for that matter) of a pipe even when the command is often used inside a pipeline in the synopsis section. > For keyword signs that are already used in expressing the grammar, we could > quote the sign to indicate that it is a keyword : "(" .
Following several issues with the way the formatting of synopsis is done in the manpages that were recently reworked, this patch series introduces the processing of a new custom paragraph attribute 'synopsis'. This extension is added to asciidoc and asciidoctor and lets write the synopsis of the commands without any typeset. 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 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 Documentation/CodingGuidelines | 34 ++++++++++++++----------- Documentation/asciidoc.conf | 12 +++++++++ Documentation/asciidoctor-extensions.rb | 17 +++++++++++++ Documentation/git-clone.txt | 20 +++++++-------- Documentation/git-init.txt | 12 ++++----- t/t0450-txt-doc-vs-help.sh | 11 +++----- 6 files changed, 68 insertions(+), 38 deletions(-) base-commit: ad57f148c6b5f8735b62238dda8f571c582e0e54 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1766%2Fjnavila%2Fdoc_synopsis_para-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1766/jnavila/doc_synopsis_para-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/1766 Range-diff vs v1: 1: 704f0333ef1 ! 1: aba144f4ff3 doc: introduce a synopsis custom paragraph attribute @@ Documentation/asciidoc.conf: git-relative-html-prefix= +ifdef::backend-docbook[] +ifdef::doctype-manpage[] +[paradef-default] -+#synopsis-style=template="verseparagraph",filter="sed -E 's!<[a-z-]+>!<emphasis>\\0</emphasis>!g' -E 's!([a-z-]+)!<literal>\\1</literal>!g'" -+synopsis-style=template="verseparagraph",filter="perl -pe 's!([\[\] |()>]|^)([=+a-zA-Z0-9-:+=]+)!\\1<literal>\\2</literal>!g;s!(<\\;[a-zA-Z0-9-.]+>\\;)!<emphasis>\\1</emphasis>!g'" -+#synopsis-style=template="verseparagraph" ++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="perl -pe 's!([\[\] |()>]|^)([+a-zA-Z0-9-:+=]+)!\\1<code>\\2</code>!g;s!(<\\;[a-zA-z0-9-.]+>\\;)!<em>\\1</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 + + 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__') ++ 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 @@ Documentation/asciidoctor-extensions.rb: module Git postprocessor Git::Documentation::DocumentPostProcessor end - ## Documentation/git-clone.txt ## -@@ Documentation/git-clone.txt: SYNOPSIS - [++--recurse-submodules++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`] - [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`] - [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_ -- [_<directory>_] -+ [__<directory>__] - - DESCRIPTION - ----------- - - ## Documentation/git-init.txt ## -@@ Documentation/git-init.txt: SYNOPSIS - [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__] - [++--ref-format=++__<format>__] - [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__] -- [++--shared++[++=++__<permissions>__]] [_<directory>_] -+ [`--shared`[++=++__<permissions>__]] [__<directory>__] - - - DESCRIPTION - ## t/t0450-txt-doc-vs-help.sh ## @@ t/t0450-txt-doc-vs-help.sh: txt_to_synopsis () { fi && b2t="$(builtin_to_txt "$builtin")" && sed -n \ - -e '/^\[verse\]$/,/^$/ { -+ -e '/^\[\(verse\|synopsis\)\]$/,/^$/ { ++ -E '/^\[(verse|synopsis)\]$/,/^$/ { /^$/d; - /^\[verse\]$/d; - s/_//g; - s/++//g; - s/`//g; -+ /^\[\(verse\|synopsis\)\]$/d; - s/{litdd}/--/g; - s/'\''\(git[ a-z-]*\)'\''/\1/g; +- s/{litdd}/--/g; +- s/'\''\(git[ a-z-]*\)'\''/\1/g; ++ /^\[(verse|synopsis)\]$/d; ++ s/\{litdd\}/--/g; ++ s/'\''(git[ a-z-]*)'\''/\1/g; + p; + }' \ 2: b0547422e5c = 2: b6387bef40d doc: update the guidelines to reflect the current formatting rules 3: 3bcbe455747 ! 3: 2a61e0945de doc: apply synopsis simplification on git-clone and git-init @@ Documentation/git-clone.txt: git-clone - Clone a repository into a new 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`] +- [`--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>__] +- [_<directory>_] +[synopsis] +git clone [--template=<template-directory>] + [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] @@ Documentation/git-init.txt: git-init - Create an empty Git repository or reiniti - [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__] - [++--ref-format=++__<format>__] - [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__] -- [`--shared`[++=++__<permissions>__]] [__<directory>__] +- [++--shared++[++=++__<permissions>__]] [_<directory>_] +[synopsis] +git init [-q | --quiet] [--bare] [--template=<template-directory>] + [--separate-git-dir <git-dir>] [--object-format=<format>]