Asp Forum - The Making of Copland's User Manual

Bil Kleb

10/6/2004 11:09:00 AM

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.lar...
on Rails). Is the process you used described somewhere that
all can benefit from?

Thanks,
--
Bil Kleb, Hampton, Virginia

7 Answers

Jamis Buck

10/6/2004 1:19:00 PM

Bil Kleb wrote:
> 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.lar...
> 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

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

Gavin Sinclair

10/6/2004 1:40:00 PM

On Wednesday, October 6, 2004, 11:19:26 PM, Jamis wrote:

>> Is the process you used described somewhere that all can benefit
>> from?

> 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

10/6/2004 2:47:00 PM

Gavin Sinclair wrote:
> On Wednesday, October 6, 2004, 11:19:26 PM, Jamis wrote:
>
>
>>>Is the process you used described somewhere that all can benefit
>>>from?
>
>
>>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

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

Bil Kleb

10/7/2004 1:25:00 PM

Jamis Buck wrote:
>
> 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,
--
Bil Kleb, Hampton, Virginia

Jamis Buck

10/7/2004 1:38:00 PM

Bil Kleb wrote:
> Jamis Buck wrote:
>
>>
>> 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.

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|

>
>> 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.

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

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

Gavin Sinclair

10/7/2004 2:23:00 PM

On Thursday, October 7, 2004, 11:38:26 PM, Jamis wrote:

> Bil Kleb wrote:
>> Jamis Buck wrote:
>>
>>>
>>> 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.

> 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

10/7/2004 2:55:00 PM

Gavin Sinclair wrote:
> On Thursday, October 7, 2004, 11:38:26 PM, Jamis wrote:

>>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.

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

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

comp.lang.ruby

The Making of Copland's User Manual

Bil Kleb

Jamis Buck

Gavin Sinclair

Jamis Buck

Bil Kleb

Jamis Buck

Gavin Sinclair

Jamis Buck

x Login to ForumsZone