Status on HgBook

[Martin Geisler]

"Bryan O'Sullivan" <bos at serpentine.com> writes:

> On Fri, Nov 5, 2010 at 9:36 AM, Martin Geisler <mg at aragost.com> wrote:
>>
>> It's not just about being ugly, it's also about getting better output
>> and a better tool-chain... I just tried to compile the book and I was
>> able to get HTML output. For the PDF, I got funny errors about XSLT
>> stylesheets not being found and I read something about setting a Java
>> class path.
>
> I'd suggest that you don't worry about building the PDF.

But, but... I'm used to worry quite a bit about how my PDFs are built
using LaTeX :)

> The FO stuff used for that is deeply unpleasant, and all the free FO
> tools I've used have been broken.

Okay, I'll think of the book as a HTML-project then.

>> In other words: I'm much more comfortable with an Python tool-chain
>> and produce some good-looking LaTeX code from that instead of relying
>> on the weird Docbook XML stuff.
>
> It's actually pretty easy to generate good HTML from DocBook XML. And
> honestly, DocBook is actually pretty decent to write with if you give
> it a chance. I've written two entire books in it, so I should know :-)

Yeah, I know -- they are both here on my bookshelf :) So, now that we've
settled that, I guess the first step should be to move the translations
into a unified system based on Gettext.

I think it would be good to setup some automated builds so that we can
see the progress for the different languages. Should that be hosted on
red-bean.com? I notice that hgbook.net is available -- we could perhaps
also host it on mercurial.selenic.com/book?

When we have a good setup like that, we can begin updating the book to
work with Mercurial 1.7+.

If I understood it correctly, then the output of the examples is just
included directly, with no checking? I would like to have both the input
and output in the source, just like I do it as my kick start guides.
There I write

  .. shelltest::
     :name: alice

     $ ls
     $ hg init example
     $ ls
     example

to let "Alice" create a repository and the input/outputs are all
verified during the compilation. I find it nice to have the examples
directly in the source instead of including them with an entity.

It should be easy to do something similar in Docbook, I'm imagining it
would look like this:

  <shellsession name="alice">
  <![CDATA[
    $ ls
    $ hg init example
    $ ls
    example
  ]]>
  </shellsession>

When compiled, the prompts should be highlighted and the output should
be verified. There is no shellsession element defined, but can we define
our own? I found the programlisting and screen elements, so maybe we can
use one of those?

-- 
Martin Geisler

Mercurial links: http://mercurial.ch/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <http://selenic.com/pipermail/mercurial/attachments/20101107/602ccc8f/attachment.pgp>