git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Jeff King <peff@peff.net>
To: Michael J Gruber <git@drmicha.warpmail.net>
Cc: Thomas Ackermann <th.acker66@arcor.de>, git@vger.kernel.org
Subject: Re: [Patch 0/5] Create single PDF for all HTML files
Date: Mon, 15 Oct 2012 13:42:43 -0400	[thread overview]
Message-ID: <20121015174243.GA31658@sigill.intra.peff.net> (raw)
In-Reply-To: <507BF9C7.1080601@drmicha.warpmail.net>

On Mon, Oct 15, 2012 at 01:55:51PM +0200, Michael J Gruber wrote:

> > I wonder if a more sane route is to drop HTML entirely, convert the
> > asciidoc to docbook (which we already do for manpages), and then create
> > a docbook document that is a collection of all elements, which can then
> 
> Hmm, I think the html output often looks better than the man output
> (tables and such), and it is a formatted, reflowable, interlinked format
> fit for many puposes.

It does look better, but that is because the docbook->roff step is where
things get ugly. In theory, docbook is at least as expressive as HTML,
and has lots of nice semantic markup that gives us flexibility in what
the final product looks like.

There are docbook->epub converters (I think xmlto will do this out of
the box), as well as a host of other formats. But convincing docbook to
create a collection of "refentry" (their term for manpage) articles is
harder than you'd think. I tried a few things when this thread started
and couldn't get anything simple to work (xml has managed to make the
simple act of "include this document in this other document" insanely
complex). But I only spent a few minutes on it.

> > be converted to pdf, epub, or whatever. I would not be surprised if
> > somebody has solved this problem before (but it is not really my itch,
> > so I did not look very far).
> 
> I'd rather ditch docbook and have one toolchain (asciidoc, unless we
> want to switch to something else) only... We've been hunting asciidoc as
> well as docbook compatibility (between versions) and interoperability
> (between them) issues again and again.

Yeah, I really hate our doc toolchain. It just seems like everything
else is even worse. We can ditch docbook, but then how do we make
manpages?

-Peff

  reply	other threads:[~2012-10-15 17:43 UTC|newest]

Thread overview: 23+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2012-10-06 15:51 [Patch 0/5] Create single PDF for all HTML files Thomas Ackermann
2012-10-06 15:53 ` [Patch 1/5] Fix some asciidoc layout problems Thomas Ackermann
2012-10-06 18:39   ` Junio C Hamano
2012-10-06 19:10     ` Jeff King
2012-10-07  8:01     ` Aw: " Thomas Ackermann
2012-10-06 15:55 ` [Patch 2/5] Create html documents for all files in Documentation/technical Thomas Ackermann
2012-10-06 18:45   ` Philip Oakley
2012-10-06 15:55 ` [Patch 3/5] Create html documents for all files in Documentation/RelNotes Thomas Ackermann
2012-10-06 18:48   ` Philip Oakley
2012-10-06 19:21   ` Jeff King
2012-10-07 20:53     ` Junio C Hamano
2012-10-15 11:48       ` Michael J Gruber
2012-10-15 20:49         ` Junio C Hamano
2012-10-06 15:57 ` [Patch 4/5] Create html documents for all files in Documentation/howto Thomas Ackermann
2012-10-06 15:58 ` [Patch 5/5] Create pdf from all html files Thomas Ackermann
2012-10-06 19:11   ` Jeff King
2012-10-06 19:32 ` [Patch 0/5] Create single PDF for all HTML files Jeff King
2012-10-07 20:54   ` Junio C Hamano
2012-10-07  8:14 ` Aw: " Thomas Ackermann
2012-10-07 22:52   ` Jeff King
2012-10-15 11:55     ` Michael J Gruber
2012-10-15 17:42       ` Jeff King [this message]
2012-10-08 22:53   ` Philip Oakley

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20121015174243.GA31658@sigill.intra.peff.net \
    --to=peff@peff.net \
    --cc=git@drmicha.warpmail.net \
    --cc=git@vger.kernel.org \
    --cc=th.acker66@arcor.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).