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

On 2009 Mar 23, at 11:22, Junio C Hamano wrote:

An issue that came up recently was that the backticks seem to have no typeset representation in the official kernel.org manpages.

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).