Ruby and user documentation

Ruby
1

Hi all,

I just finished a quite large business project (in 1.9, pure ruby, not
Rails, with GUIs in FXRuby). I want to write a documentation for users
(not the code doc, I use Yard for it). Of course I can produce doc files
or PDF files.

But I’d like to stay in the Ruby ecosystem. What would do suggest ?
Prawn, Sinatra … ? Do you know examples (with reusable patterns) ?

Thanks.
_md

2

2010/3/26 Michel D. [email protected]:

I just finished a quite large business project (in 1.9, pure ruby, not
Rails, with GUIs in FXRuby). I want to write a documentation for users
(not the code doc, I use Yard for it). Of course I can produce doc files
or PDF files.

But I’d like to stay in the Ruby ecosystem. What would do suggest ?
Prawn, Sinatra … ? Do you know examples (with reusable patterns) ?

OpenOffice. Seriously, for end user documentation which typically
also includes graphics etc. I’d pick a tool that provides automatism
like TOC generation etc. and has a graphical UI which allows to
control the layout while editing. My 0.02EUR.

Kind regards

robert

3

Robert K. wrote:

OpenOffice. Seriously, for end user documentation which typically
also includes graphics etc. I’d pick a tool that provides automatism
like TOC generation etc. and has a graphical UI which allows to
control the layout while editing. My 0.02EUR.

Kind regards

robert

Robert, this is what I have started doing, but I have now quite large
and unlinked files. I’d like to give the user the possibility to
navigate between small chunks (Windows help like). Is there a OO (or
Word) format directly available for such things ?

4

On Mar 26, 4:15 am, Michel D. [email protected] wrote:

Hi all,

I just finished a quite large business project (in 1.9, pure ruby, not
Rails, with GUIs in FXRuby). I want to write a documentation for users
(not the code doc, I use Yard for it). Of course I can produce doc files
or PDF files.

But I’d like to stay in the Ruby ecosystem. What would do suggest ?
Prawn, Sinatra … ? Do you know examples (with reusable patterns) ?

I would use a markup language for the files, probably Markdown*. HTML
is the “universal language” so that should be the end product. But you
can also generate PDFs for print. You can always write pre- and post-
processors for any specialized patterns you might need --indeed you
might find that others have already done it for you. Also, if I may
toot my own horn for a second, have a look at QED which would allow
you to test your code examples directly.

Another route, especially if your ultimate goal is printing a book,
you might look into how the Pragmatic Programmers handle it --I think
they use XML and their own DTD.

*AsciiDoc is well regarded too, but it does lie outside the strict
domain of Ruby tools.

5

2010/3/26 Michel D. [email protected]:

Word) format directly available for such things ?
AFIK you can have hyperlinks in OO files - and they can even point to
other OO files (relative paths should work). I believe you can even
preserve them in exported PDF files. You can also create books
composed of multiple individual files. Does that help you?

Kind regards

robert

6

Thomas S. wrote:

I would use a markup language for the files, probably Markdown*. HTML
is the “universal language” so that should be the end product. But you
can also generate PDFs for print. You can always write pre- and post-
processors for any specialized patterns you might need --indeed

Thomas, I was thinking of something of that kind. I use Git-Wiki (and
Textile, but Markdown is similar) for a personal CMS.

you might find that others have already done it for you.
That is more or less what I was looking for :wink:

Also, if I may
toot my own horn for a second, have a look at QED which would allow
you to test your code examples directly.
I’ll have a look at it. Thanks
_md

7

Robert K. wrote:

2010/3/26 Michel D. [email protected]:

Word) format directly available for such things ?
AFIK you can have hyperlinks in OO files - and they can even point to
other OO files (relative paths should work). I believe you can even
preserve them in exported PDF files. You can also create books
composed of multiple individual files. Does that help you?

Kind regards

robert

Actually, as I work on Windows, I can use Word (which yes has links to
internal bookmarks). But I tried to find a better tool. For instance, I
am not able in Word (I did not try in OO) to link automagically every
instance of a given word to a specific bookmark : it does not seem
possible to paste a linked word in the “replace all” field without
loosing the link… This I can do in any markup source, even in LaTeX.
Or by hacking a Word macro, shame !

Well, maybe I want too much. On has apparently to choose between
manipulating images in a markup language or hacking links in a WISIWIG.
I do not know which solution I hate more !
_md

8

On Fri, Mar 26, 2010 at 9:55 AM, Michel D. [email protected]
wrote:

I do not know which solution I hate more !
_md

If you want automagic links, you might try out the note-taking
application Tomboy: Apps/Tomboy - GNOME Wiki!

It has automagic linking and you can export stuff as linked formatted
HTML.

Maybe not the perfect solution, but one to consider.

-Jonathan N.

9

Intransition wrote:

Prawn, Sinatra … ? Do you know examples (with reusable patterns) ?

I would use a markup language for the files, probably Markdown*. HTML
is the “universal language” so that should be the end product. But you
can also generate PDFs for print.

I like the combination of markdown (via the kramdown[1] gem) and
webby[2]. You can embed graphviz diagrams, gnuplots, syntax
highlighting, TeX formulas, etc, with webby managing the dependencies
via rake.

Another point for HTML output (which is what webby produces) is that you
can build CHM, which some windows users may expect.

ps. glad to hear of the major use of fxruby. Congrats!

[1] http://kramdown.rubyforge.org/

[2] http://webby.rubyforge.org/

10

Joel VanderWerf wrote:

Intransition wrote:

Prawn, Sinatra … ? Do you know examples (with reusable patterns) ?

I would use a markup language for the files, probably Markdown*. HTML
is the “universal language” so that should be the end product. But you
can also generate PDFs for print.

I like the combination of markdown (via the kramdown[1] gem) and
webby[2]. You can embed graphviz diagrams, gnuplots, syntax
highlighting, TeX formulas, etc, with webby managing the dependencies
via rake.

Another point for HTML output (which is what webby produces) is that you
can build CHM, which some windows users may expect.

ps. glad to hear of the major use of fxruby. Congrats!

[1] http://kramdown.rubyforge.org/

[2] http://webby.rubyforge.org/

Thanks Joel. I had a look at kramdown, but did not know webby. I’ll try.
_md

11

Jonathan N. wrote:

On Fri, Mar 26, 2010 at 9:55 AM, Michel D. [email protected]
wrote:
If you want automagic links, you might try out the note-taking
application Tomboy: Apps/Tomboy - GNOME Wiki!

It has automagic linking and you can export stuff as linked formatted
HTML.

Maybe not the perfect solution, but one to consider.

-Jonathan N.

Jonathan, thanks for the tip, I’ll try Tomboy.
Thanks to all for your precious advices.

_md

12

Michel D. schrieb:

Thanks.
_md

docbook --for all your documentation.

  • docbook is the default documentation system fro Linux (LDP), gnome,
    kde.
  • You are free to use whatever editor or wordprocessor, you like;
    including:
    Microsoft Word, Apple Pages, Adobe FrameMaker, OpenOffice (all via
    Roundtrip).
  • Offers the best SVG integration for graphics --gnuplot features a SVG
    backend.
  • Many target formats such as unix manual pages, texinfo, javadoc,
    eclipse,
    htmlhelp, epub, pdf, postscript, printing, SVG (and Flash) , html,
    xhtml, LaTeX, …
  • Converting source code tags for Rdoc or yard into docbook is
    simple. The markup is handled by the docbook toolchain, all you got
    to
    do is analyse the source code commentary --if possible reuse Rdoc or
    yard for this.
    I ve done this for Jeszra:
    Chapter 9. Documentation

-roger

13

Arndt Roger S. wrote:

Michel D. schrieb:

Thanks.
_md

docbook --for all your documentation.

-roger

Roger, I like your doc, and I discovered Jeszra. Thanks!
_md

14

Arndt Roger S. wrote:

-roger

Roger,

thanks for this advice. Yes, your solution seems exactly fit to my
needs. I’ll dive in it.

_md

15

Michel D. schrieb:

-roger

Roger, I like your doc, and I discovered Jeszra. Thanks!
_md

Thanks.
I made a thorough survey of DTP Software before I’ve started to write
Jeszra’s documentation
in docbook; and believe me I did not want to use DocBook at all.

However, technical documents must be in plain text to put them under
version control, easily chunkable, allow for re-arrangement, reuse, and
must
support different target formats (html, pdf …).

Finally you will end with something XML-based --such as docbook.
The single other serious docbook contender is DITA.

Concering Jeszra’s documentation: the html version still uses too-many
raster images, because SVG support is lagging behind in some browsers.
I did almost completely eliminate raster images from the pdf versions.

SVG support in html will improve alot over the next year (with
Microsoft’s commitment to
SVG in IE9) and the new epub readers (SVG is part of the epub
specification).

BTW: the docbook epub part is written in Ruby.

-roger

16

Allan D. wrote:

My recomendation is Sphinx. http://sphinx.pocoo.org/
This is a python user documentation tool that uses restructured text and
outputs html, pdf, htmlhelp.

Allan, I code with NetBeans, and am trying to use it for writing DocBook
files. Hard ! Is there a NetBeans plugin for Sphinx editing ? This would
do the trick !

_md

17

Netbeans itself does not reconize the .rst extention yet. but I have
written
a ant script to build sphinx and I just create a freeform project with
this
antscript and that does the trick

I have attached the ant script just rename the name attribute on the
project
tag

Allan D.
Member of NetBeans Dream Team
http://wiki.netbeans.org/NetBeansDreamTeam
Lead Developer, nbPython
http://wiki.netbeans.org/Python
http://codesnakes.blogspot.com (my blog)
Co-Chair, CajunJUG
http://www.cajunjug.org

18

Allan D. wrote:

Netbeans itself does not reconize the .rst extention yet. but I have
written
a ant script to build sphinx and I just create a freeform project with
this
antscript and that does the trick

Thanks Allan.
I have now plenty of options and shall experiment…
_md

19

Michel D. wrote:

I have now plenty of options and shall experiment…
_md

Just for closing the thread.

This is what I am doing :

  1. Input doc in asciidoc markup format,
  2. Convert to docbook XML, (using python library), then build html doc
    (or whatever else) by XSLT processing.

Thanks to all.
_md

For info, the Win batch file :

C:\Python26\python.exe C:\Python26\Lib\asciidoc\asciidoc.py -b docbook
tempo.txt 2>asciidoc.log
C:\docbook\libxslt\bin\xsltproc.exe --nonet --stringparam
chunk.section.depth 0 --xinclude --timing F:\docbook\xsl\html\chunk.xsl
tempo.xml 2>xslt.log

20

My recomendation is Sphinx. http://sphinx.pocoo.org/
This is a python user documentation tool that uses restructured text and
outputs html, pdf, htmlhelp.

Allan D.
Member of NetBeans Dream Team
http://wiki.netbeans.org/NetBeansDreamTeam
Lead Developer, nbPython
http://wiki.netbeans.org/Python
http://codesnakes.blogspot.com (my blog)
Co-Chair, CajunJUG
http://www.cajunjug.org