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
--
Posted via http://www.ruby-forum.com/.
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
2010/3/26 Michel Demazure <michel@demazure.com>:
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) ?
--
remember.guy do |as, often| as.you_can - without end
http://blog.rubybestpractices.com/
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.
On Mar 26, 4:15 am, Michel Demazure <mic...@demazure.com> 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) ?
Michel Demazure schrieb:
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
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
Robert Klemme 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 ?
--
Posted via http://www.ruby-forum.com/\.
Thomas Sawyer 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 
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
--
Posted via http://www.ruby-forum.com/\.
Intransition 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.
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/
On Mar 26, 4:15 am, Michel Demazure <mic...@demazure.com> wrote:
Arndt Roger Schneider wrote:
Michel Demazure schrieb:
Thanks.
_mddocbook --for all your documentation.
+ docbook is the default documentation system fro Linux (LDP), gnome,
kde.
...
I ve done this for Jeszra:
Chapter 9. Documentation-roger
Roger, I like your doc, and I discovered Jeszra. Thanks!
_md
--
Posted via http://www.ruby-forum.com/\.
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
2010/3/26 Michel Demazure <michel@demazure.com>:
Robert Klemme 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.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 ?
--
remember.guy do |as, often| as.you_can - without end
http://blog.rubybestpractices.com/
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!
Thanks Joel. I had a look at kramdown, but did not know webby. I'll try.
_md
--
Posted via http://www.ruby-forum.com/\.
Michel Demazure schrieb:
Arndt Roger Schneider wrote:
Michel Demazure schrieb:
Thanks.
_mddocbook --for all your documentation.
+ docbook is the default documentation system fro Linux (LDP), gnome, kde.
...
I ve done this for Jeszra:
Chapter 9. Documentation-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
Robert Klemme wrote:
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
Arndt Roger Schneider wrote:
-roger
Roger,
thanks for this advice. Yes, your solution seems exactly fit to my
needs. I'll dive in it.
_md
--
Posted via http://www.ruby-forum.com/\.
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 Nielsen
On Fri, Mar 26, 2010 at 9:55 AM, Michel Demazure <michel@demazure.com> wrote:
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
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 Davis
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
On Sun, Mar 28, 2010 at 7:32 AM, Michel Demazure <michel@demazure.com>wrote:
Arndt Roger Schneider wrote:
> -roger
Roger,
thanks for this advice. Yes, your solution seems exactly fit to my
needs. I'll dive in it._md
--
Posted via http://www.ruby-forum.com/\.
Jonathan Nielsen wrote:
On Fri, Mar 26, 2010 at 9:55 AM, Michel Demazure <michel@demazure.com> > 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 Nielsen
Jonathan, thanks for the tip, I'll try Tomboy.
Thanks to all for your precious advices.
_md
--
Posted via http://www.ruby-forum.com/\.
Allan Davis 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
--
Posted via http://www.ruby-forum.com/\.
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
build.xml (1.3 KB)
--------------------------------------------------------------
Allan Davis
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
On Mon, Mar 29, 2010 at 8:24 AM, Michel Demazure <michel@demazure.com>wrote:
Allan Davis 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
--
Posted via http://www.ruby-forum.com/\.
Allan Davis 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
--
Posted via http://www.ruby-forum.com/\.
Michel Demazure 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
--
Posted via http://www.ruby-forum.com/\.