| Message ID | 20240320091748.GA2444639@coredump.intra.peff.net (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 9dc75d81b809135fdf60181e9eb87cd6058a1a21 |
| Headers | show |
| Series | doc/gitremote-helpers: fix more missing single-quotes | expand |
Jeff King <peff@peff.net> writes: > There are a few cases left in gitremote-helpers.txt that are missing a > closing quote, so you end up with: > > 'option deepen-since <timestamp> > > with a stray opening quote instead of rendering correctly in italics. > These should have been part of 51d41dc243 (doc/gitremote-helpers: fix > missing single-quote, 2024-03-07), but apparently my eyesight is not > what it once was. Hopefully this is now all of them. Thanks. $ git grep -e "^\(['][^']*['][^']*\)*['][^']*::" Documentation does not have any more hits after this patch.
Le 20/03/2024 à 10:17, Jeff King a écrit : > There are a few cases left in gitremote-helpers.txt that are missing a > closing quote, so you end up with: > > 'option deepen-since <timestamp> > > with a stray opening quote instead of rendering correctly in italics. > These should have been part of 51d41dc243 (doc/gitremote-helpers: fix > missing single-quote, 2024-03-07), but apparently my eyesight is not > what it once was. Hopefully this is now all of them. > > Signed-off-by: Jeff King <peff@peff.net> > --- > This should go on top of jk/doc-remote-helpers-markup-fix. > > Documentation/gitremote-helpers.txt | 6 +++--- > 1 file changed, 3 insertions(+), 3 deletions(-) > > diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt > index 83e99192e1..cd4e16abad 100644 > --- a/Documentation/gitremote-helpers.txt > +++ b/Documentation/gitremote-helpers.txt > @@ -470,14 +470,14 @@ set by Git if the remote helper has the 'option' capability. > 'option depth' <depth>:: > Deepens the history of a shallow repository. > > -'option deepen-since <timestamp>:: > +'option deepen-since' <timestamp>:: > Deepens the history of a shallow repository based on time. > > -'option deepen-not <ref>:: > +'option deepen-not' <ref>:: > Deepens the history of a shallow repository excluding ref. > Multiple options add up. > > -'option deepen-relative {'true'|'false'}:: > +'option deepen-relative' {'true'|'false'}:: > Deepens the history of a shallow repository relative to > current boundary. Only valid when used with "option depth". The syntax for describing alternatives is specified as (true|false). Also, in my reworks of syntax, I chose to remove all formatting from the term parts of the description lists. Thanks
Jean-Noël Avila <avila.jn@gmail.com> writes: >> -'option deepen-relative {'true'|'false'}:: >> +'option deepen-relative' {'true'|'false'}:: >> Deepens the history of a shallow repository relative to >> current boundary. Only valid when used with "option depth". > > The syntax for describing alternatives is specified as (true|false). Hmmmm, here, true and false are to be given verbatim. > Also, in my reworks of syntax, I chose to remove all formatting from the > term parts of the description lists. I know we added the _<placeholder>_ thing, but have we added these to Documentation/CodingGuidelines yet? Thanks.
On Thu, Mar 21, 2024 at 11:28:01AM +0100, Jean-Noël Avila wrote: > > -'option deepen-relative {'true'|'false'}:: > > +'option deepen-relative' {'true'|'false'}:: > > Deepens the history of a shallow repository relative to > > current boundary. Only valid when used with "option depth". > > The syntax for describing alternatives is specified as (true|false). > > Also, in my reworks of syntax, I chose to remove all formatting from the > term parts of the description lists. I don't have an opinion on the typesetting of true/false here, but this does match the rest of the document. If you have another series fixing them all up, I'm happy if it overrides this patch (as long as the rendering error is fixed one way or the other). -Peff
Le jeudi 21 mars 2024, 17:25:56 CET Junio C Hamano a écrit : > Jean-Noël Avila <avila.jn@gmail.com> writes: > > >> -'option deepen-relative {'true'|'false'}:: > >> +'option deepen-relative' {'true'|'false'}:: > >> Deepens the history of a shallow repository relative to > >> current boundary. Only valid when used with "option depth". > > > > The syntax for describing alternatives is specified as (true|false). > > Hmmmm, here, true and false are to be given verbatim. In such case, it's (`true`|`false`) . As well as the command before. > > > Also, in my reworks of syntax, I chose to remove all formatting from the > > term parts of the description lists. > > I know we added the _<placeholder>_ thing, but have we added these > to Documentation/CodingGuidelines yet? > > Thanks. > > No, we haven't. I skimmed over different documentation projects and there's no real consensus on what the formatting should be in detail, except for some common rules. man-pages(7) gives some good hints that we should adhere to, which are echoed in the guide of asciidoc: https://docs.asciidoctor.org/asciidoctor/latest/ manpage-backend/ . Basically, verbatim are in bold, and variables are in italic. In our man pages, the asciidoc verbatim are rendered as bold and asciidoc emphasis are rendered as underlined, just like italics, which adheres to the principles, Note that bold/verbatim are usually also used in terms of description lists. I'm totally ok to change the CodingGuidelines and reroll git-clone and git- init with these new rules.
Jean-Noël AVILA <avila.jn@gmail.com> writes: >> Hmmmm, here, true and false are to be given verbatim. > > In such case, it's (`true`|`false`) . As well as the command before. Yes, they should be given like so, I think. >> I know we added the _<placeholder>_ thing, but have we added these >> to Documentation/CodingGuidelines yet? >> >> Thanks. > > No, we haven't. > > I skimmed over different documentation projects and there's no real consensus > on what the formatting should be in detail, except for some common rules. > man-pages(7) gives some good hints that we should adhere to, which are echoed > in the guide of asciidoc: https://docs.asciidoctor.org/asciidoctor/latest/ > manpage-backend/ . Basically, verbatim are in bold, and variables are in > italic. > > In our man pages, the asciidoc verbatim are rendered as bold and asciidoc > emphasis are rendered as underlined, just like italics, which adheres to the > principles, What I meant by "verbatim" was "what the user would give Git verbatim", which are marked up as `true` (or `false`), and typically typeset in monospace in HTML. I just checked the prerendered man pages, and indeed \fB...\fR surrounds verbatim phrases, which was a bit surprising to me. > Note that bold/verbatim are usually also used in terms of description lists. > > I'm totally ok to change the CodingGuidelines and reroll git-clone and git- > init with these new rules. So to go back to the original example, what do we want to do instead of ... 'option deepen-relative' {'true'|'false'}:: ... this? Like this ... `option deepen-relative` (`true`|`false`):: ... or something else? Thanks.
Le dimanche 24 mars 2024, 03:19:38 CET Junio C Hamano a écrit : > Jean-Noël AVILA <avila.jn@gmail.com> writes: > > >> Hmmmm, here, true and false are to be given verbatim. > > > > In such case, it's (`true`|`false`) . As well as the command before. > > Yes, they should be given like so, I think. > > >> I know we added the _<placeholder>_ thing, but have we added these > >> to Documentation/CodingGuidelines yet? > >> > >> Thanks. > > > > No, we haven't. > > > > I skimmed over different documentation projects and there's no real consensus > > on what the formatting should be in detail, except for some common rules. > > man-pages(7) gives some good hints that we should adhere to, which are echoed > > in the guide of asciidoc: https://docs.asciidoctor.org/asciidoctor/latest/ > > manpage-backend/ . Basically, verbatim are in bold, and variables are in > > italic. > > > > In our man pages, the asciidoc verbatim are rendered as bold and asciidoc > > emphasis are rendered as underlined, just like italics, which adheres to the > > principles, > > What I meant by "verbatim" was "what the user would give Git > verbatim", which are marked up as `true` (or `false`), and typically > typeset in monospace in HTML. I just checked the prerendered man > pages, and indeed \fB...\fR surrounds verbatim phrases, which was a > bit surprising to me. > In asciidoc legacy mode, the "verbatim" is two-sided : tell asciidoc to not interpret the content (in modern mode, this is no longer true) but also format the snippet in a way to indicate to the reader that this is a constant part of the syntax. On this formatting surprise, the current behavior, verbatim as bold, is inherited from xmlto's special option manpage-bolt-literal.xsl of processing docbook and differs from asciidoctor's direct conversion which formats the verbatim as monospace in the roff output. When converting the roff file to ps or pdf, the format difference stands out and some form of markup is preserved, but in the console, monospace is lost. So, with our current setup, if we shift to pure asciidoctor for compiling the docs, without further postprocessing, we may end up loosing in part this useful formatting for console manpages, something I had overlooked. If we keep using the docbook format as a pivot format, then we're safe. Side Note : for man pages that are translated, pure asciidoctor is currently used and this special conversion is not applied. > > Note that bold/verbatim are usually also used in terms of description lists. > > > > I'm totally ok to change the CodingGuidelines and reroll git-clone and git- > > init with these new rules. > > So to go back to the original example, what do we want to do instead > of ... > > 'option deepen-relative' {'true'|'false'}:: > > ... this? Like this ... > > `option deepen-relative` (`true`|`false`):: > > ... or something else? With our currrent guidelines, this latest markup is the right one. I will change the CodingGuidelines in another patch series to add more litteral formats in the synopsis and in the terms of description lists, so as to converge toward the generally accepted format of manpages.
Jean-Noël AVILA <avila.jn@gmail.com> writes: > I will change the CodingGuidelines in another patch series to add more > litteral formats in the synopsis and in the terms of description lists, so as > to converge toward the generally accepted format of manpages. OK. Thanks.
diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index 83e99192e1..cd4e16abad 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -470,14 +470,14 @@ set by Git if the remote helper has the 'option' capability. 'option depth' <depth>:: Deepens the history of a shallow repository. -'option deepen-since <timestamp>:: +'option deepen-since' <timestamp>:: Deepens the history of a shallow repository based on time. -'option deepen-not <ref>:: +'option deepen-not' <ref>:: Deepens the history of a shallow repository excluding ref. Multiple options add up. -'option deepen-relative {'true'|'false'}:: +'option deepen-relative' {'true'|'false'}:: Deepens the history of a shallow repository relative to current boundary. Only valid when used with "option depth".
There are a few cases left in gitremote-helpers.txt that are missing a closing quote, so you end up with: 'option deepen-since <timestamp> with a stray opening quote instead of rendering correctly in italics. These should have been part of 51d41dc243 (doc/gitremote-helpers: fix missing single-quote, 2024-03-07), but apparently my eyesight is not what it once was. Hopefully this is now all of them. Signed-off-by: Jeff King <peff@peff.net> --- This should go on top of jk/doc-remote-helpers-markup-fix. Documentation/gitremote-helpers.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)