Hi Stefan, On 14 oct. 2012, at 17:03, Stefan Seelmann <[email protected]> wrote:
> On 10.10.2012 16:42, Pierre-Arnaud Marcelot wrote: >>> I wanted to ask about the documentation system. Some time ago there was >>> agreement to use version controlled files with wiki synatx that is >>> transformed to docbook and then further transformed to HTML/PDF. Is this >>> still the case or did something change? >> >> Nothing changed at the moment, but I think it raises the question of a >> switch to Markdown on that part of the documentation too. >> Maybe it's better if we share the same syntax between the website and the >> documentation systems. > > I agree that using Markdown for the documentation makes sense. > Convertion should be straigh forward. However the currently used > toolchain (especially Eclipse Mylyn WikiText which is used for editing > and for converting wiki syntax to docbook within the maven build) does > not support markdown [1]. Indeed. :-( However, I personally do the documentation work outside of Eclipse using: - BBEdit as text editor with markdown syntax highlighting - Marked as a Markdown visualizator - command line to generate the website locally before committing modifications >>> I ask also wrt to the ongoing >>> migration of the website to the Apache CMS: when using the CMS is it >>> still possible to add static content (i.e. the generated documentation) >>> to the website? >> >> Yeah, this is supported by the Apache CMS. >> The static content can be added directly in subversion or it can be >> compressed into an archive and imported via the online Apache CMS, see [1] > > Thanks for the pointers, Pierre-Arnaud. > > Anyway, even it is possible I still wonder if we should continue with > the current system (Maven project in SVN, edited at local computer, > documents generated via Maven build) or if we should move the content to > the CMS. I wonder too. > Let me just write down some pros/cons of each system here, they descirbe > my current POV, please correct me if I'm wrong and add additional arguments. > > Pros of current system: > * HTML and PDF output > * Thanks to DocBook a TOC and navigation links are generated > * Probably easiser to handle different versions (ApacheDS 2.0, 2.1, 3.0) > using branches and merge changes between branches (but do we really do > that?) The current system should also allow us to automatically include the documentation in other Maven projects. We could, for example, include the ApacheDS user guide as HTML and/or PDF within the release of ApacheDS itself. Same thing for Studio and the LDAP API. > Cons of current system: > * Changes are not immediately visible on the website > * Separate steps required to publish the HTML to the website > * Layout of HTML output does not look exactly like the website layout The layout can certainly be updated to look almost similar, so I'm not sure it's really an issue. I would add one more item to the current system's cons: * Different syntax being used to edit the website and documentation files > Pros of CMS solution: > * Changes are immediately visible > * Easier usage and patch creation for non-committers [2] > * Editing in webbrowser or offline > > Cons of CMS solution: > * No PDF generation OOTB, but it should be possible to use the CMS > folder as source, but needs some work Same thing for automation and re-usability of the documentation in other Maven projects. The choice between the two systems isn't really easy. Maybe we should try to create a utility to generate a PDF from markdown text. I've seen some project which can convert from Markdown text to DocBook format. Maybe it could be a solution. Regards, Pierre-Arnaud > Kind Regards, > Stefan > > [1] https://bugs.eclipse.org/bugs/show_bug.cgi?id=329528 > [2] http://www.apache.org/dev/cmsref.html#non-committer >
