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 Kleb, Hampton, Virginia
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.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
--
Jamis Buck
jgb3@email.byu.edu
http://www.jamisbuck.org/jamis
[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
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:
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
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.org/jamis
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.org/jamis
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
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.
Gavin Sinclair 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
On Thursday, October 7, 2004, 11:38:26 PM, Jamis wrote:
--
Jamis Buck
jgb3@email.byu.edu
http://www.jamisbuck.org/jamis