| Message ID | pull.1766.v5.git.1727161730.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | doc: introducing synopsis para | expand |
"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.
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)
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/
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).
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.
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