Re: [RFC/WIP 0/2] Documentation clean-up: git commands

[Michael J Gruber <git@drmicha.warpmail.net>]

Chris Johnsen venit, vidit, dixit 24.03.2009 00:13:
> On 2009 Mar 23, at 11:22, Junio C Hamano wrote:
>> Michael J Gruber <git@drmicha.warpmail.net> writes:
>>
>>> - Do we want it this way (`git command`)?
>>
>> That's my personal preference but other people may differ; wasn't  
>> there an
>> issue with "man" backend losing the typesetting information?
> 
> An issue that came up recently was that the backticks seem to have no  
> typeset representation in the official kernel.org manpages.

The man backend seems to handle ` and ' differently, that's true. But
that's an issue of the asciidoc configuration in combination with the
docbook stylesheets. In any case, backticks are for commands.

I'm grateful if you look into the asciidoc/docbook issues. We also have
compatibility issues going on there between different asciidoc 8
versions, as well as docbook versions.

> In my recent fumbling with the documentation generation, I have often  
> been using git-init.txt as a "test bed". It shows clearly enough that  
> backticks, by themselves, are not represented in the official manpages:
> 
> $ git grep core/templates Documentation/git-init.txt
>   Documentation/git-init.txt:directory is `/usr/share/git-core/ 
> templates`.
> 
> There we see the path in backticks with a period outside the  
> backticks. If any inline typesetting were to come between "core/ 
> templates" and ".", I think this command would turn it up:
> 
> $ git log -p -Score/templates. origin/man -- man1/git-init.1
> 
> It gets two hits. The first where the sentence is introduced, and a  
> second where the period is escaped:
> 
> 43e513c (Autogenerated man pages for v1.5.0-rc1, 2007-01-12)
> 2cbdf46 (Autogenerated manpages for v1.5.6.2-212-g08b5, 2008-07-06)
> 
> The last one leaves us with "core/templates\.". So search again to  
> see if that has changed since the last one:
> 
> git log -p -Score/templates\\. origin/man -- man1/git-init.1
> 
> Nope, that only shows the one hit (2cbdf46). In case I made an error  
> using the `git log` to do the searching, I also checked by hand by  
> loading the diffs from <http://git.kernel.org/?p=git/ 
> git.git;a=history;f=man1/git-init.1;hb=man> (they agree, no  
> formatting around that path in any of the generated git-init.1).
> 
> When I generate the manpage on my machine (asciidoc 8.3.1; docbook- 
> xsl 1.74.0), I do get some formatting for backticks:
> 
> $ grep core/templates Documentation/git-init.1
> Provide the directory from which templates will be used\&. The  
> default template directory is \FC/usr/share/git\-core/templates\F[]\&.
> 
>  From what I can tell the \FC is supposed to introduce monospace type  
> and \F[] is to reset to the previous type. When I run it through  
> groff -man -Tps, it  does come out in a monospaced font. The change  
> in font is not obvious when viewing the manpage in a tty-based  
> manpage viewer (which was my original "gripe"), but there is some  
> typesetting info there for pages I generate.
> 
> I suspect the main difference between my generated pages and the  
> official pages (at least for typesetting of literal text) is the  
> docbook-xsl version (though I have not dug into previous versions of  
> dcobook-xsl to bolster this hypothesis).
> 
> I have a series of patches prepared to "cleanup" and modify  
> {callout,manpage-1.72}.xsl and asciidoc.conf, but I am still running  
> a series of "make doc" runs across the changes to try to make sure  
> they are sane. Here is a preview:
> 
> Documentation: move callouts.xsl to manpage-{base,normal}.xsl
> Documentation: use parametrized manpage-base.xsl with manpage- 
> {1.72,normal}.xsl
> Documentation: rename docbook-xsl-172 attribute to git-asciidoc-no-roff
> Documentation: move quieting params into manpage-base.xsl
> Documentation: move "spurious .sp" code into manpage-base.xsl
> Documentation: asciidoc.conf: always use <literallayout> for [blocktext]
> Documentation: asciidoc.conf: fix verse block with block titles
> Documentation: option to render literal text as italic for manpages
> 
> The first three restructure things a bit. The next three make some  
> cleanups that could be dropped if they are deemed inappropriate. The  
> last one add an option that changes the manpage formatting used  
> around asciidoc backticked strings (literal text).
> 
> I plan on sending the patches along after my trial doc-generations  
> finish and I have reviewed the results (my machine is slow, it may  
> not be until tomorrow).
>