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