git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [Patch 0/5] Create single PDF for all HTML files

From
Jeff King <peff@peff.net>
Date
Oct 15, 2012, 17:42 UTC
Message-ID
<20121015174243.GA31658@sigill.intra.peff.net>
In-Reply-To
<507BF9C7.1080601@drmicha.warpmail.net>
On Mon, Oct 15, 2012 at 01:55:51PM +0200, Michael J Gruber wrote:
Show 7 quoted lines
> > 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.

Show 8 quoted lines
> > 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
Previous: Michael J GruberNext: Philip Oakley
Message 21 of 23 in “Create single PDF for all HTML files”
  1. 0/5 Create single PDF for all HTML filesThomas Ackermann, Oct 6, 2012
  2. 1/5 Fix some asciidoc layout problemsThomas Ackermann, Oct 6, 2012
  3. Junio C HamanoOct 6, 2012
  4. Jeff KingOct 6, 2012
  5. Aw: Re: [Patch 1/5] Fix some asciidoc layout problemsThomas Ackermann, Oct 7, 2012
  6. 2/5 Create html documents for all files in Documentation/technicalThomas Ackermann, Oct 6, 2012
  7. Philip OakleyOct 6, 2012
  8. 3/5 Create html documents for all files in Documentation/RelNotesThomas Ackermann, Oct 6, 2012
  9. Philip OakleyOct 6, 2012
  10. Jeff KingOct 6, 2012
  11. Junio C HamanoOct 7, 2012
  12. Michael J GruberOct 15, 2012
  13. Junio C HamanoOct 15, 2012
  14. 4/5 Create html documents for all files in Documentation/howtoThomas Ackermann, Oct 6, 2012
  15. 5/5 Create pdf from all html filesThomas Ackermann, Oct 6, 2012
  16. Jeff KingOct 6, 2012
  17. Jeff KingOct 6, 2012
  18. Aw: Re: [Patch 0/5] Create single PDF for all HTML filesThomas Ackermann, Oct 7, 2012
  19. Jeff KingOct 7, 2012
  20. Michael J GruberOct 15, 2012
  21. Jeff KingOct 15, 2012
  22. Philip OakleyOct 8, 2012
  23. Junio C HamanoOct 7, 2012

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.