[Grok-dev] Grok website status?

[Kevin Teague]

>
> I vaguely remember hearing something about the ReST issues during the
> Neanderthal sprint, but can anyone remind me what they are?
>

The ReST issues are:

  1. Description fields in Plone can only be plain text, and do not  
allow for HTML. This means that some descriptions have ReST formatting  
showing through, e.g.:

     http://plone.grok.quintagroup.com/documentation/tutorial/introductory-tutorial

     I'm not sure if/what the discussion has been to do about this?  
Possible solutions:

      * Edit descriptions so that they are just in plain-text and not  
ReST.

      * Hack Plone to render descriptions only in PHC as ReST  
(probably pretty ugly to do, so I doubt this is a feasible  
solution ... although I did do this for a Plone 1 install waaay back)

  2. code-block and sidebar directive: these are not rendering, e.g.

     http://plone.grok.quintagroup.com/documentation/tutorial/macros-with-grok/accessing-zope3-standard-macros

     Darryl Cousins sent me a package called 'resthack' which has  
directives for these two ReST directives. There is a bug preventing  
the package from working though, and this is where I left off ... I  
haven't given it a proper crack at trying to fix though, and I'm going  
to work on this next. The package also includes some pygments code, so  
presumably we can also get Python syntax highlighting for the code- 
block directives.

  3. include directives do not work. e.g.

      http://plone.grok.quintagroup.com/documentation/tutorial/introductory-tutorial/publishing-a-simple-web-page/view

      From the ReST issues grok sprint notes (http://wiki.zope.org/grok/WebsiteToDos 
), "file including is not possible in Plone. Because we get a  
traceback I commented the occurences of file inclusions. Please have a  
look at the tutorials. The included source code can either be copied  
and pasted from the source file or we must enable Plone to include  
code from filesystem inside Plone Help Center. Martijn proposed to  
make a script for the main tutorial, which splits up the rst-file into  
chapters, incorporates the contents of the code files and put it  
somehow into Plone."

  4. Other small issues mentioned on the sprint to-do such as  
"References/Links inside a tutorial with or without an anchor must be  
fixed according to the new structure of the tutorials"

5. Overall PHC usage policies: I know Martijn would like to have the  
main Tutorial in ReST in SVN, e.g. "Martijn proposed to make a script  
for the main tutorial, which splits up the rst-file into chapters,  
incorporates the contents of the code files and put it somehow into  
Plone." For the other mini-tutorials and how-tos do we want:

   a. Keep all these in SVN as well and sync from SVN into PHC

   b. Keep all these in PHC-only in ReST

   c. Keep all these in PHC and alllow the primary author to choose  
their format

    My vote is for option c. but what do others think?

    Aside from the main Grok Tutorial, which is a special case,  
syncing the other content from SVN has the issue that where the  
boundaries between individual pages get choosen means that we have  
pages that are getting chopped into too small of sections, e.g.:

    http://plone.grok.quintagroup.com/documentation/tutorial/macros-with-grok/macros-with-grok

    The idea of allowing only ReST in PHC would be that we could pull  
this content from Plone and include it in Grok release tarballs.