Re: user-manual.html invalid HTML

From: Jeff King <peff@peff.net>
To: Jonathan Nieder <jrnieder@gmail.com>
Cc: jidanni@jidanni.org, git@vger.kernel.org,
	Junio C Hamano <gitster@pobox.com>
Subject: Re: user-manual.html invalid HTML
Date: Sat, 21 Aug 2010 02:21:22 -0400	[thread overview]
Message-ID: <20100821062122.GA28735@coredump.intra.peff.net> (raw)
In-Reply-To: <20100820050401.GC25013@burratino>

On Fri, Aug 20, 2010 at 12:04:02AM -0500, Jonathan Nieder wrote:

> > The versions I build locally have:
> > 
> > <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
> >     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
> > 
> > in each HTML file, which is added by asciidoc.  Maybe the package you
> > are looking at was built with an older version of asciidoc that doesn't
> > do this (I don't actually know the history of this feature, but it seems
> > to me that this is something asciidoc should be doing, not git).
> 
> It looks like the HTML for user-manual.html (unlike the reference
> manual and other articles) is not generated by asciidoc after all;
> instead, the rule in Documentation/Makefile uses xsltproc directly to
> convert the asciidoc-generated XML to HTML.

Thanks for tracking this down.

> Apparently the caller is supposed to set the
> chunker.output.doctype-public parameter.
> http://www.sagehill.net/docbookxsl/Chunking.html#OutputDoctype

Your patch works fine for me, though I am using the exact same toolchain
as you. I have no idea if older docbook's will work less well.

> + <xsl:output method="html"
> +     encoding="UTF-8" indent="no"
> +     doctype-public="-//W3C//DTD HTML 4.01//EN"
> +     doctype-system="http://www.w3.org/TR/html4/strict.dtd" />

My asciidoc-generated pages are xhtml. We are using "html/docbook.xsl"
from docbook, and now "xhtml", so probably some form of html is right.
But is html4 strict right? With nothing else to go on, it seems a good
guess to me, but I'm wondering if you actually found the answer
somewhere.

Also, while testing your patch, I found and fixed the following buglet:

-- >8 --
Subject: [PATCH] docs: fix Makefile dependency for user manual

We use our custom xsl file to build the user manual, so make
sure we depend on it. We don't use it anywhere else, so we
can stick it straight in the rule.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/Makefile |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index a4c4063..e117bc4 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -279,7 +279,7 @@ $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt
 XSLT = docbook.xsl
 XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
 
-user-manual.html: user-manual.xml
+user-manual.html: user-manual.xml $(XSLT)
 	$(QUIET_XSLTPROC)$(RM) $@+ $@ && \
 	xsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \
 	mv $@+ $@
-- 
1.7.2.2.350.g9c7e
