[Grok-dev] New Grok site: restructured text and HTML

[Uli Fouquet]

Hi there,

I am happy to see, that the number of howtos, tutorials and the like on
the new grok site is growing really fast since we switched to the Plone
site. Many thanks to all contributers!

Most of the new documents were written in HTML (with Kupu, I assume).
IMHO this is problematic, because we can not easily convert it to
Restructured Text which in turn makes it difficult to include your
documents in any new grok release documentation.

Kevin already told here on the list, how you can enable
restructuredText-mode for editing, which I will repeat here for
convenience::

  1) Go to:

     http://plone.grok.quintagroup.com/personalize_form

     and disable Kupu.

  2) Add/edit your document and enable 'restructured text' as mode for
     content editing (this does not seem to work for descriptions). 
     Note, that you might have to reset this each time before saving 
     your document.

If you're in a hurry, you might still use Kupu/HTML, because HTML is
better than nothing, but consider to convert your documents later on or
drop me a note, so I can do it for you.

Restructured Text is really easy to learn. You can get a first
impression here::

  http://docutils.sourceforge.net/docs/user/rst/quickstart.html

For writing reference-API documentation, you might want to use the
extended set of ReST markup that is supported by the new Grok-Site. This
extended markup is explained roughly here::

  https://svn.gnufix.de/repos/rest-extensions/trunk/USAGE.txt

A usage example is the reference itself.

There is also the possibility to stop maintenance of `doc/` in the grok
trunk or to reduce it to a minimum number of README files pointing to
the website. Then it wouldn't matter, in which format documents are
created. The drawback would be, that there would be no 'canonical'
documentation of certain versions. Switching to HTML also in the trunk
documentation is not an option IMHO.

Meanwhile, I added the complete reference documentation from the trunk
to the new site (ReST-format, of course, but still unpublished; only
logged in users can see it). Kevin and me managed to get all special
markup of the reference to be parsed without warnings/errors (thanks,
Kevin!), although the rendered output is still under (CSS-)construction.
People who checked out the gzo-packages to build a local grok-site,
might want to update their sources.

BTW: PloneHelpCenter documents are great in processing standalone ReST  
     docs. But problems arise, when you link to other internal 
     documents. TocTrees, for example, are not generated, because   
     they would have to process several 'files'/documents. Is there a 
     Plone product, that can handle complete 'trees' of rest documents? 
     Or should one be written? Could PHC be extended to support such 
     processing? To summarize: an import/export action would be nice 
     here. Maybe I am to dumb to see an already available way.

Kind regards,

-- 
Uli