Writing documentation in YAML - any advice?

ruby-talk
1

It will be a decent sized document. WinXP platform.

Where should I start / look for help with:

- Decent editor with decent YAML mode; if I don't find any I'll probably
settle for JEdit.

- Useful YAML type declarations for a document

- Ability to mix in some formatting mark-up

- Useful ruby scripts to manipulate e.g. generate toc, index, html, check
validity, ...

- Any ways to modularize into smaller documents/files a'la XInclude

All help appreciated. A ready gem would be great :slight_smile: Suggestions along the
lines of "don't do it ... do it this way instead" also welcome.

Thanks

2

Its Me wrote:

It will be a decent sized document. WinXP platform.

Where should I start / look for help with:

- Decent editor with decent YAML mode; if I don't find any I'll probably
settle for JEdit.

- Useful YAML type declarations for a document

- Ability to mix in some formatting mark-up

- Useful ruby scripts to manipulate e.g. generate toc, index, html, check
validity, ...

- Any ways to modularize into smaller documents/files a'la XInclude

All help appreciated. A ready gem would be great :slight_smile: Suggestions along the
lines of "don't do it ... do it this way instead" also welcome.

No "ready gems" available that I know of. However, if you don't mind mining other projects for ideas:

   * Why's Poignant Guide to Ruby (http://rubyforge.org/projects/poignant/\). His entire book is done in YAML, using textile markup.

   * Copland (http://rubyforge.org/projects/copland\). The user manual for Copland is done very similarly to the Poignant Guide.

   * Needle (http://rubyforge.org/projects/needle\). The user manual for needle is done similarly to the Guide and Copland, but instead of putting the marked-up text directly in the YAML document, the YAML references external files that contain the content.

Those should give you some ideas, and hopefully get you started.

- Jamis

···

--
Jamis Buck
jgb3@email.byu.edu
http://www.jamisbuck.org/jamis

3

Its Me wrote:

It will be a decent sized document. WinXP platform.

Where should I start / look for help with:

- Decent editor with decent YAML mode; if I don't find any I'll probably
settle for JEdit.

- Useful YAML type declarations for a document

- Ability to mix in some formatting mark-up

> ...

Why not use a document markup language rather than a data markup language?

James Britt

4

And while you're in Why's neighborhood, check out hobix, too.

s.

···

On Mon, 25 Oct 2004 09:07:44 +0900, Jamis Buck <jgb3@email.byu.edu> wrote:

No "ready gems" available that I know of. However, if you don't mind
mining other projects for ideas:

   * Why's Poignant Guide to Ruby
(http://rubyforge.org/projects/poignant/\). His entire book is done in
YAML, using textile markup.

5

Any you would specifically suggest? I find XML (and Docbook etc.) painful in
a regular text editor, and have not found any reasonable wsywig-ish
alternatives.

···

"James Britt" <jamesUNDERBARb@neurogami.com> wrote

Why not use a document markup language rather than a data markup language?

6

James Britt <jamesUNDERBARb@neurogami.com> wrote in message news:<417D3752.7080306@neurogami.com>...

Why not use a document markup language rather than a data markup language?

Either way, YAML ain't a markup language, or so I've heard. :slight_smile:

7

Why not just use Textile (http://www.textism/textile\)? You can use
RedCloth to convert it to HTML.

···

On Tue, 26 Oct 2004 00:49:06 +0900, Its Me <itsme213@hotmail.com> wrote:

"James Britt" <jamesUNDERBARb@neurogami.com> wrote
> Why not use a document markup language rather than a data markup language?

Any you would specifically suggest? I find XML (and Docbook etc.) painful in
a regular text editor, and have not found any reasonable wsywig-ish
alternatives.

8

IIRC, there are lots of ways to do this--though "wsywig" can (and
should) only be taken so far when you are dealing with semantic markup.
Lyx was what I recalled using, but googling for it I found all of these
as well:

       http://wiki.docbook.org/topic/DocBookAuthoringTools

-- Markus

···

On Mon, 2004-10-25 at 08:49, Its Me wrote:

"James Britt" <jamesUNDERBARb@neurogami.com> wrote
> Why not use a document markup language rather than a data markup language?

Any you would specifically suggest? I find XML (and Docbook etc.) painful in
a regular text editor, and have not found any reasonable wsywig-ish
alternatives.

9

Its Me wrote:

Why not use a document markup language rather than a data markup language?

Any you would specifically suggest? I find XML (and Docbook etc.) painful in
a regular text editor, and have not found any reasonable wsywig-ish
alternatives.

Well, if indeed docbook bothers you, then perhaps plain XHTML, using
class attributes to carry semantic metadata. Or LaTex. Or Postscript.

I've found large (100+ lines) YAML files difficult and error-prone to
work with, what with the indentation requirements, and datatype-centric
design, and find the idea of markup-soup perplexing.

I don't see the appeal of embedding HTML or Textile inside of YAML. You
seem to get the worst of both worlds.

Personal taste, perhaps.

James

···

"James Britt" <jamesUNDERBARb@neurogami.com> wrote

10

Karl von Laudermann wrote:

Either way, YAML ain't a markup language, or so I've heard. :slight_smile:

That only means that the *intended* purpose of YAML is *not* doing markup. It does not mean that it cannot be used for that purpose.

Ruby is a *programming* language but the German edition of the c.l.r FAQ (which I happen to maintain, URL see signature) is a proof-of-concept that shows the possibility of writing documents in plain Ruby.

According to the original definition I am therefore a hacker: Someone who (ab)uses something for an unintended purpose.

Josef 'Jupp' Schugt <jupp(a)gmx(d)de>

···

--
Messages larger than 100 KiB will be discarded *without* notification
http://oss.erdfunkstelle.de/ruby/ German ed. of comp.lang.ruby FAQ

11

"Bill Atkins" <batkins57@gmail.com> wrote in message

Why not just use Textile (http://www.textism/textile\)? You can use
RedCloth to convert it to HTML.

Ah. Because I need my own specific semantic markup as well, interleaved
somewhat freely with general xhtml-ish narrative.

12

James Britt wrote:

I don't see the appeal of embedding HTML or Textile inside of YAML. You
seem to get the worst of both worlds.

Personal taste, perhaps.

Definitely there are minor annoyances that I'll be smoothing out over the next little while. The largest of these (folding of lines) will be finessed with the upcoming RedCloth 3. Hopefully, we can keep working toward something even better than the current setup.

I feel YAML + Textile is ideal for writing a book. (However, I haven't taken a book to the printer's yet, so I have yet to confront that reality.)

YAML serves three purposes in my doc format:

1. metadata regarding the text (allow licensing info and
2. to provide hierarachy for chapters and sections (specifically for
generating the table of contents)
3. custom content (sidebars, tip boxes)

Textile blocks reside in the book sections, comprising the bulk of the book's text. I prefer Textile to other simple markups, because it allows assignment of CSS IDs and classes to elements.
For example, if I have a paragraph I'd like to hilite:

    p(hilite). Despite the surge of power you feel upon learning Ruby,
    resist the urge to trip others or slap them in the bald head.
    DO NOT LORD YOUR RUBYNESS OVER OTHERS!

The goal is to allow hooks into the CSS class with RedCloth, so that
the PDF generator can format those paragraphs, if desired.

The indentation complaint is reasonable. I guess it's a toss up between continual indentation and XML's start and end tags.

Embedding Textile in XML seems like a disaster, since I'd have to ensure that entities are encoded and such. YAML is worryfree, since I can embed anything as long as it's indented.

All in all, the combination has made all kinds of writing very smooth.

_why

13

why the lucky stiff wrote:

For example, if I have a paragraph I'd like to hilite:

   p(hilite). Despite the surge of power you feel upon learning Ruby,
   resist the urge to trip others or slap them in the bald head.
   DO NOT LORD YOUR RUBYNESS OVER OTHERS!

LOL -- I practically fell off my chair.

Thanks,

···

--
Bil Kleb, Hampton, Virginia

14

That's going into my .sig rotation :slight_smile:

···

On Oct 27, 2004, at 4:34 AM, Bil Kleb wrote:

Despite the surge of power you feel upon learning Ruby,
resist the urge to trip others or slap them in the bald head.
DO NOT LORD YOUR RUBYNESS OVER OTHERS!

--
(-, /\ \/ / /\/

15

Of course you shouldn't.

Obvious.

You should write a couple of lines of ruby to trip them up, shave 'em
bald and slap them over the head.

THAT WAY YOU CAN LORD IT OVER ALL OF THEM!

John Carter Phone : (64)(3) 358 6639
Tait Electronics Fax : (64)(3) 359 4632
PO Box 1645 Christchurch Email : john.carter@tait.co.nz
New Zealand

The universe is absolutely plastered with the dashed lines exactly one
space long.

···

On Wed, 27 Oct 2004, Bil Kleb wrote:

why the lucky stiff wrote:

For example, if I have a paragraph I'd like to hilite:

   p(hilite). Despite the surge of power you feel upon learning Ruby,
   resist the urge to trip others or slap them in the bald head.
   DO NOT LORD YOUR RUBYNESS OVER OTHERS!

LOL -- I practically fell off my chair.