Project

General

Profile

Forums » Open discussion »

Redmine for creating documentation

Added by Jean-Claude Wippler over 12 years ago

Redmine's wiki has been evolving very nicely over the years, and now I'm wondering how far we would be from using it as a publication mechanism for (technical) documentation:

  • the wiki page hierarchy supports the structure needed for creating one or more "books"
  • the online HTML navigation through breadcrumbs already works well
  • possible refinement: add prev/next links (i.e. between pages with the same parent)
  • child page ordering is currently alphabetical - this would be an issue, see below
  • PDF page generation is pretty good, but it'll need to support inline images at some point

My dream would be to be able to point to a wiki page and generate a complete PDF document from it, with all the child pages included. That way you end up with a live(ly) web site which can evolve and grow through collaboration, and with care the whole thing could also be used to generate one or more PDF document: tutorials, user guides, reference guides, etc.

It would not be at the level of a hand-made PDF with front matter and index, but still - fine for taking with you and reading from start to finish, one the things books are good for.

The main design stumbling block I can see is page ordering: how to control the order of child pages in relation to their parent page. This also applies to the "Index by title" page, which currently uses alphabetical ordering.

One workaround would be to force the order by naming page "1. First page", "2. Second page", etc - but that would affect all internal page links.

Another way out would be to bypass automatic tree traversal altogether, and generate the book from a dedicated page which lists all the child pages in the proper order. It's a more manual effort, and it would not change the current "Index by title" page, which I think might also benefit from a controllable order.

An lastly, a "hack" would be to add a dedicated page and actually insert all content right there using the {{include}} macro. The page would be fairly easy to edit, but viewing it as HTML might be extremely slow and resource-consuming. I haven't tried it yet. I'm also not sure what this would do to embedded {{toc}} macros.

How does this sound? Worth pursuing? Been discussed before? Feasible? Any major stumbling blocks you can think of?


Replies (5)

RE: Redmine for creating documentation - Added by Mischa The Evil over 12 years ago

Jean-Claude Wippler wrote:

Redmine's wiki has been evolving very nicely over the years, and now I'm wondering how far we would be from using it as a publication mechanism for (technical) documentation:

  • the wiki page hierarchy supports the structure needed for creating one or more "books"
  • the online HTML navigation through breadcrumbs already works well
  • possible refinement: add prev/next links (i.e. between pages with the same parent)
  • child page ordering is currently alphabetical - this would be an issue, see below

These four together sounds a lot like the thing that the Redmine Wiki Books plugin (https://github.com/txinto/redmine_wiki_books) is/was implementing.

  • PDF page generation is pretty good, but it'll need to support inline images at some point

Individual wiki page PDF export was implemented for #401 and support for attachment images in PDF export was implemented for #3261 (both released in Redmine 1.3.0).
All wiki pages PDF export was implemented for #3463 (1.4.0).

RE: Redmine for creating documentation - Added by Jean-Claude Wippler over 12 years ago

Thanks. I'm using the 2.0 branch now.

The github repo is available, but the gatatac.net site isn't right now.

The PDF export does not show images in the 2.0.4 rev I'm using right now. I can't find any config settings for this. Shall I submit a bug report?

RE: Redmine for creating documentation - Added by Mischa The Evil about 12 years ago

Jean-Claude Wippler wrote:

Thanks. I'm using the 2.0 branch now.

So, this functionality should be available for you.

Jean-Claude Wippler wrote:

The github repo is available, but the gatatac.net site isn't right now.

It still isn't. At least the source is on GitHub so it can be forked to make it compatible with Redmine 2.x.

Jean-Claude Wippler wrote:

The PDF export does not show images in the 2.0.4 rev I'm using right now. I can't find any config settings for this. Shall I submit a bug report?

For this to work there are several requirements according to the info provided in #3261:
  • RMagick must be available; thus also ImageMagick
  • Images must be attachments of the specific wiki-page, referenced with the !image-filename.ext! syntax (thus external url images are not supported [see #9693])
  • Supported image formats are jpeg, png & gif (extension is required)

If these requirements are all met, feel free to open a new issue if needed.

Hope this helps...

RE: Redmine for creating documentation - Added by Mano Went over 11 years ago

For inspirations, i found a online editor for technical documents a half year ago. I like the use of reStructuredText to get a latex or pdf document.

The address of the site is notex.ch

RE: Redmine for creating documentation - Added by Txinto Vaz about 11 years ago

Hi, I am the developer of Redmine Wiki Books. After more than a year far from the project, I recently updated it to work with 2.x.x Redmine (currently tested only on 2.3.2, but I want to test it on the more recent ones).

Unfortunately I lost previous tutorials, but I have quickly edited a little book to see it in action:

http://gatatac.org/books/1

Thanks for the reference to the plugin, Mischa.

It is very interesting to automatically generate a PDF from the book.

Best regards.

Tx.

    (1-5/5)