The Making of Copland's User Manual

[Bil Kleb]

Jamis,

During the conference, I only caught the tail end of your
remarks about how you created Copland's user manual. Our
team is currently facing a similar task (in addition to
getting the rest of our website, http://fun3d.larc.nasa.gov
on Rails). Is the process you used described somewhere that
all can benefit from?

Thanks,

 

[Jamis Buck]

Jamis,

During the conference, I only caught the tail end of your
remarks about how you created Copland's user manual. Our
team is currently facing a similar task (in addition to
getting the rest of our website, http://fun3d.larc.nasa.gov
on Rails). Is the process you used described somewhere that
all can benefit from?

Thanks,

Bil,

For my Copland manual, I took a page (quite literally) from _why's book.
The "Poignant Guide" uses a ruby script to process a YAML document,
turning it into a lovely, attractive suite of HTML pages. I lifted
_why's ruby script and erb templates, tweaked them a bit, and dropped
them into my Copland project.

The process is something like this:

1) Create a YAML document that contains your manual metadata, as well as
the content of your manual in textile format. (A few gotchas to be
avoided there, if you decide to go that route--just let me know.) Use
YAML to structure your manual, defining chapters and sections as array
and hash elements.

2) Create (or modify) erb templates to suit the look you want for your
manual.

3) Create (or modify) a stylesheet to define the look of your manual.

4) Create (or modify) a ruby script to process your YAML document.

5) Run the ruby script to convert your YAML document into HTML.

Feel free to grab Copland and look at the "doc/manual" subdirectory. You
can build the manual easily by running "rake manual".

Incidentally, my Net::SSH project uses the same process for its user
manual. And of course, WPGTR is the definitive source for the whole
process, incorporating many more features than mine does (like sidebars,
and a printable version).

Hope that helps,

Jamis

 

[Gavin Sinclair]

For my Copland manual, I took a page (quite literally) from _why's book.
The "Poignant Guide" uses a ruby script to process a YAML document,
turning it into a lovely, attractive suite of HTML pages. I lifted
_why's ruby script and erb templates, tweaked them a bit, and dropped
them into my Copland project.

The process is something like this:

[snip process]

Thanks Jamis. I'm most interested in this, too, having spent far too
much time today trying to massage a messy collection of Textile documents
into a cohesive unit. Phew!!

Gavin

 

[Jamis Buck]

For my Copland manual, I took a page (quite literally) from _why's book.
The "Poignant Guide" uses a ruby script to process a YAML document,
turning it into a lovely, attractive suite of HTML pages. I lifted
_why's ruby script and erb templates, tweaked them a bit, and dropped
them into my Copland project.

The process is something like this:

[snip process]

Thanks Jamis. I'm most interested in this, too, having spent far too
much time today trying to massage a messy collection of Textile documents
into a cohesive unit. Phew!!

Gavin

Really, all thanks should go to _why. I didn't add anything original
beyond what _why already had done.

As usual, he's bushwhacking new territory in the unmapped interior of
Ruby Possibilities.

Thanks, _why!

- Jamis

 

[Bil Kleb]

1) Create a YAML document that contains your manual metadata, as well as
the content of your manual in textile format. (A few gotchas to be
avoided there, if you decide to go that route--just let me know.)

I am considering this route, please expand.

5) Run the ruby script to convert your YAML document into HTML.

Does anyone have a script that would convert to something that could
produce a nice hardcopy? For example, LaTeX.

Hope that helps,

Yes.

Thanks,

 

[Jamis Buck]

I am considering this route, please expand.

Mostly, the gotchas have to do with some subtle interactions between
YAML and Textile. For example, in strings, YAML will join lines, unless
there are two newlines between them. Thus, when authoring your document,
you have to add one more line than usual between paragraphs, or list
elements, etc. For example:

key: >
This will all be
joined in one line.

This will be part of the above paragraph, separated
by a line break (<br>).


This is a new paragraph.


* This is a list element.

* This is another element in the same list.

It makes for a lot of whitespace (as you may have noticed, if you've
looked at the sources for Copland's manual.)

This also means that if you are using the little style-hint elements for
block elements (like tables and so forth), you need to put _two_
newlines after them:

key: >
Here is a table:


table(list).

|column 1a|column 1b|column 1c|

|column 2a|column 2b|column 2c|

Does anyone have a script that would convert to something that could
produce a nice hardcopy? For example, LaTeX.

I seem to recall _why saying that he's got RedCloth converting some
Textile strings to LaTeX. Don't know how far that's gone. (Seems like
he's got so many projects on his plate, I'm surprised he gets anything
done.)


- Jamis

 

[Gavin Sinclair]

Mostly, the gotchas have to do with some subtle interactions between
YAML and Textile. For example, in strings, YAML will join lines, unless
there are two newlines between them. Thus, when authoring your document,
you have to add one more line than usual between paragraphs, or list
elements, etc.

That kind of pernickety crap annoys me. I'd rather put the Textile in
files, and refer to those files in the YAML.

Cheers,
Gavin

 

[Jamis Buck]

That kind of pernickety crap annoys me. I'd rather put the Textile in
files, and refer to those files in the YAML.

I agree, it was annoying until I got used to it. You could just as
easily do as you say, though, which would probably be a nicer solution
anyway.

chapters:
- Introduction: !!file intro.txt
- Quick Start: !!file start.txt
...

It certainly reduces the "noise" in the config file. And it would only
require a few minor tweaks to the script...

Hmmm. I need to stop reading this list. I makes way to much work for me.

- Jamis