RE: [Yaml-core] Spec Formats?

[Oren Ben-K. <or...@ri...>]

Neil Watkiss [mailto:neilw@ActiveState.com] wrote:
> I'm strongly leaning towards GNU Info after reading to 
> documentation for 'makeinfo'...

I've written documentation using TexInfo. It is a nice system, I agree.

> Here are the formats I could find that it outputs:
> 
>    a) info
>       $ makeinfo yaml.texi
>    b) plain text
>       $ makeinfo --text yaml.texi > yaml.txt
>    c) HTML
>       $ makeinfo --html yaml.texi

TexInfo is high level enough so that this should, in principle, result in
good quality HTML (maybe even using CSS). Any idea how well this works in
practice? (HTML wasn't around when I used TexInfo :-)

>    d) DocBook
>       $ makeinfo --docbook yaml.texi

Any idea on how well this works? It seems some work is invested in the
opposite direction - DocBook to TexInfo; and GNU seem intent on migrating
from TexInfo to DocBook as their standard documentation format,
"eventually".

>    e) [La]TeX
>       $ tex yaml.texi # OR
>       # texi2dvi yaml.texi

Presumably TeX would be used to create PDF files as well... The main problem
there would be fonts. TeX's default fonts aren't PDF-friendly AFAIK;
overriding them isn't a big thing if you know how to muck with TeX files.
I'm *extremely* rusty on this, last time I worked with TeX (actually LaTex)
was 1993...

>    f) XML (TexinfoML, whatever that is)
>       $ makeinfo --xml yaml.texi
>
> I'm pretty much sold on it. Truth be told, I haven't check 
> whether you can get this stuff on Windows (I know it works
> in Cygwin). I imagine you can, since it's just a simplified
> TeX.

I'm actually running Cygwin on my laptop, so it is no big deal.

The main problem with TexInfo is that it is very restrictive. Like 4GLs and
trains it is great if it gets you where you want to go but is PITA if you
need to get anywhere off the predetermined track.

For example, it seems TexInfo will make it rather hard to format the BNF
productions. It has no built-ins for it and it doesn't allow access to
low-level formatting commands for building such support. That's one reason
my thesis was written using LaTeX using the "syntax" macro package...

I've fallen behind on my schedule so I didn't have time to create a new
version of the YAML spec... I'll try to get to it this weekend.

Have fun,

	Oren Ben-Kiki