Re: [AD] Pandoc

[ Thread Index | Date Index | More lists.liballeg.org/allegro-developers Archives ]


On Feb 6, 2008 1:42 PM, Peter Wang <novalazy@xxxxxxxxxx> wrote:
> Hi,
>
> Following up from the recent Allegro hack day conversation, I'm
> proposing to use Pandoc for documentation.  It basically takes the same
> approach as Haskell makedoc I proposed, but:
>
> 1. it reads in a *nice* lightweight syntax
> 2. it's maintained by someone else
>
> http://johnmacfarlane.net/pandoc/
> Apparently Windows binaries are available.
>
> I've attached a small example of how we might use it.  Pandoc has some
> deficiencies for us, but these are pretty minor:
>
> - It doesn't support file includes.  My solution is to use a small
>   script which looks for "@include FILE" markers and generates one big
>   file for Pandoc to process.
>
> - Cross reference support isn't so great, although good enough.  See
>   inside the zip file for details.

Hm..

[al_map_rgb]: #al_map_rgb

I wonder if we could ask them to auto-create reference points for all
headings, like e.g. mediawiki markup does. But then, it would not be a
real problem, as long as small awkward things like this aren't adding
up and we end up with makedoc-like markup in the end.

> - It doesn't yet output Texinfo.  I've mostly written an output driver
>   which does.  It will be available in time.
>
> - It doesn't output split HTML files.  We can add that support, or
>   process each section as a separate document and combine them somehow.

You mean something like:

manual.md:
...
@include graphics.md
@include sound.md

graphics.md:
...
@include al_map_rgb.md

In which case I think, it should work nicely. We'd have to fix
cross-references if they are processed separately, but shouldn't be
too hard.

> Maybe we can convince the author to fix the first two as well.
>

That would be nice, especially if done in a way so also split HTML can
be done easily :)

> A few days ago I added an output driver into my Haskell makedoc program
> that can convert allegro._tx into a format readable by Pandoc, so we can
> easily do a once-off conversion.

Will be useful especially for changelog and thanks files I guess - the
old API docs on the other hand can stay in the 4.4 branch, except if
we want to have a big test case for pandoc, or want to also get rid of
makedoc for 4.4.

> As Stepan Roh wrote in 2005:
>
>     I think it is time to decide what to do with Allegro documentation. It has
>     been discussed for so long, there is a new XML-based format, there are
>     several makedoc tools. But we are still stuck with _tx and C makedoc.
>
> So, that's that.

[ ] docs ---> [x] docs




Mail converted by MHonArc 2.6.19+ http://listengine.tuxfamily.org/