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@xxxxxxxxxxxxxxxxxxxx> 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). > -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
