[ 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