Why is git-subtree docs XML and not HTML?

Why is git-subtree docs XML and not HTML?

[Sebastian Schuberth]

Hi,

I'm currently looking at subtree's Makefile and wondering why the
generated markup docs is git-subtree.xml, and not git-subtree.html
like for the rest of the git commands. I have not looked at
git-subtree.xml because I'm lacking asciidoc right now, but is it just
a matter of changing the file extension from .xml to .html, or does
generating a HTML file involve more work?

-- 
Sebastian Schuberth

Re: Why is git-subtree docs XML and not HTML?

[Jeff King]

On Tue, Oct 29, 2013 at 03:03:40PM +0100, Sebastian Schuberth wrote:

> I'm currently looking at subtree's Makefile and wondering why the
> generated markup docs is git-subtree.xml, and not git-subtree.html
> like for the rest of the git commands. I have not looked at
> git-subtree.xml because I'm lacking asciidoc right now, but is it just
> a matter of changing the file extension from .xml to .html, or does
> generating a HTML file involve more work?

The XML is an intermediate format for the manpage; the original source
is .txt, from which asciidoc generate docbook .xml, from which xmlto
generate the roff git-subtree.1.

If you want HTML, you need to have asciidoc generate .html from the .txt
directly (you probably _can_ generate it from docbook, but that is more
complicated, and not how regular git commands work).

I think this would do what you want:

diff --git a/contrib/subtree/Makefile b/contrib/subtree/Makefile
index 435b2de..e9026da 100644
--- a/contrib/subtree/Makefile
+++ b/contrib/subtree/Makefile
@@ -21,6 +21,7 @@ GIT_SUBTREE    := git-subtree
 GIT_SUBTREE_DOC := git-subtree.1
 GIT_SUBTREE_XML := git-subtree.xml
 GIT_SUBTREE_TXT := git-subtree.txt
+GIT_SUBTREE_HTML := git-subtree.html
 
 all: $(GIT_SUBTREE)
 
@@ -46,6 +47,10 @@ $(GIT_SUBTREE_XML): $(GIT_SUBTREE_TXT)
 	asciidoc -b docbook -d manpage -f $(ASCIIDOC_CONF) \
 		-agit_version=$(gitver) $^
 
+$(GIT_SUBTREE_HTML): $(GIT_SUBTREE_TXT)
+	asciidoc -b xhtml11 -d manpage -f $(ASCIIDOC_CONF) \
+		-agit_version=$(gitver) $^
+
 test:
 	$(MAKE) -C t/ test
 

Re: Why is git-subtree docs XML and not HTML?

[Sebastian Schuberth]

On Tue, Oct 29, 2013 at 4:50 PM, Jeff King <peff@peff.net> wrote:

> I think this would do what you want:
>
> diff --git a/contrib/subtree/Makefile b/contrib/subtree/Makefile
> index 435b2de..e9026da 100644
> --- a/contrib/subtree/Makefile
> +++ b/contrib/subtree/Makefile
> @@ -21,6 +21,7 @@ GIT_SUBTREE    := git-subtree
>  GIT_SUBTREE_DOC := git-subtree.1
>  GIT_SUBTREE_XML := git-subtree.xml
>  GIT_SUBTREE_TXT := git-subtree.txt
> +GIT_SUBTREE_HTML := git-subtree.html
>
>  all: $(GIT_SUBTREE)
>
> @@ -46,6 +47,10 @@ $(GIT_SUBTREE_XML): $(GIT_SUBTREE_TXT)
>         asciidoc -b docbook -d manpage -f $(ASCIIDOC_CONF) \
>                 -agit_version=$(gitver) $^
>
> +$(GIT_SUBTREE_HTML): $(GIT_SUBTREE_TXT)
> +       asciidoc -b xhtml11 -d manpage -f $(ASCIIDOC_CONF) \
> +               -agit_version=$(gitver) $^
> +
>  test:
>         $(MAKE) -C t/ test
>

I just gave it a try and it works nicely:

Tested-by: Sebastian Schuberth <sschuberth@gmail.com>

Also, the clean target already contains "*.html", so nothing else to
do there. Any chance to get this queued in pu?

Thanks a lot!

-- 
Sebastian Schuberth

[PATCH] subtree: add makefile target for html docs

[Jeff King]

On Tue, Oct 29, 2013 at 05:03:53PM +0100, Sebastian Schuberth wrote:

> I just gave it a try and it works nicely:
> 
> Tested-by: Sebastian Schuberth <sschuberth@gmail.com>
> 
> Also, the clean target already contains "*.html", so nothing else to
> do there. Any chance to get this queued in pu?

Here it is with a commit message, and the additional wiring into "make
doc".

-- >8 --
Subject: subtree: add makefile target for html docs

The Makefile currently builds the roff manpage, but not the
html form. As some people may prefer the latter, let's make
it an option to build that, too. We also wire it into "make
doc" so that it is built by default.

This patch does not build or install it as part of
"install-doc"; that would require extra infrastructure to
handle installing the html as we do in git's regular
Documentation/ tree. That can come later if somebody is
interested.

Tested-by: Sebastian Schuberth <sschuberth@gmail.com>
Signed-off-by: Jeff King <peff@peff.net>
---
 contrib/subtree/Makefile | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/contrib/subtree/Makefile b/contrib/subtree/Makefile
index 435b2de..4030a16 100644
--- a/contrib/subtree/Makefile
+++ b/contrib/subtree/Makefile
@@ -21,13 +21,14 @@ GIT_SUBTREE    := git-subtree
 GIT_SUBTREE_DOC := git-subtree.1
 GIT_SUBTREE_XML := git-subtree.xml
 GIT_SUBTREE_TXT := git-subtree.txt
+GIT_SUBTREE_HTML := git-subtree.html
 
 all: $(GIT_SUBTREE)
 
 $(GIT_SUBTREE): $(GIT_SUBTREE_SH)
 	cp $< $@ && chmod +x $@
 
-doc: $(GIT_SUBTREE_DOC)
+doc: $(GIT_SUBTREE_DOC) $(GIT_SUBTREE_HTML)
 
 install: $(GIT_SUBTREE)
 	$(INSTALL) -d -m 755 $(DESTDIR)$(libexecdir)
@@ -46,6 +47,10 @@ $(GIT_SUBTREE_XML): $(GIT_SUBTREE_TXT)
 	asciidoc -b docbook -d manpage -f $(ASCIIDOC_CONF) \
 		-agit_version=$(gitver) $^
 
+$(GIT_SUBTREE_HTML): $(GIT_SUBTREE_TXT)
+	asciidoc -b xhtml11 -d manpage -f $(ASCIIDOC_CONF) \
+		-agit_version=$(gitver) $^
+
 test:
 	$(MAKE) -C t/ test
 
-- 
1.8.4.1.898.g8bf8a41.dirty

Re: [PATCH] subtree: add makefile target for html docs

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Tue, Oct 29, 2013 at 05:03:53PM +0100, Sebastian Schuberth wrote:
>
>> I just gave it a try and it works nicely:
>> 
>> Tested-by: Sebastian Schuberth <sschuberth@gmail.com>
>> 
>> Also, the clean target already contains "*.html", so nothing else to
>> do there. Any chance to get this queued in pu?
>
> Here it is with a commit message, and the additional wiring into "make
> doc".

Thanks, both.