Documentation Process test-doc (Approach 3)

This is Approach 3 of the en:Documentation_Project as defined in en:Documentation_Project_Discussion.

Official documentation will go into openacs.org/test-doc (to be renamed) generate from there the html pages for documentation, therefore the first result is to update the documentation to reflect current tools, version, correct commands, all done within that wiki instance

The process for generating technical documentation is:

1. Update that documentation wiki instance named doc-head
2. Once the documentation is ready, freeze it doing a export/import process from /doc/head to a new instance (i.e. /doc/5-5-0)
   • No write permissions for the public will be granted to this frozen instances
   • Use an alternate template to distinguish between /doc/head and the frozen ones
3. Generate the static html documentation based on the wiki-frozen instance (/doc/5-5-0) 
   • Using as template_file the view-oacs-docs
     • Available here: http://alice.wu-wien.ac.at:8000/xowiki/listing?m=list
     • Have to be placed on www dir of xowiki package
     • Also the parameter top_includelet have to be in blank for the wiki-frozen instance
     • Example on how the doc will be available in the wiki-frozen instance: http://alice.wu-wien.ac.at:8000/test-doc/for-everyone
   • Options for the static content:
     • One large HTML file and/or (book-print prototype)
     • One HTML file per chapter and/or (tutorial-advance prototype)
     • Same granularity as in /doc/head
     • Get the documentation using wget
       • This wget command should get you the html files for the documentation:
       • wget -kpr -R book <root of the documentation's xowiki instance>
     • The html files will not have an extension, this may cause them to not be interpreted as html and returned as plain text on some web servers, to be safe, rename the files to have an extension. Run the following script on the directory containing the static html files.
       • #!/bin/bash
         
         FILENAMES=`ls . | grep -v "html" | grep -v ".sh"`
         
         for f in $FILENAMES; do
             if [ ! -d "$f" ] ; then
                 FILE_NAME=`echo $f | awk -F ? '{print $1}'`
                 FILE_PARAMS=`echo $f | awk -F ? '{print $2}'`
                 if [ -z "$FILE_PARAMS" ]; then
                     NEW_FILE_NAME="${f}.html"
                 else
                     NEW_FILE_NAME="${FILE_NAME}.html?${FILE_PARAMS}"
                 fi
         
                 if [ ! -f "$NEW_FILE_NAME" ]; then
                     mv $f $NEW_FILE_NAME
                 fi
             fi
         done
         
          
4. Commit into the CVS, branch and tag appropriately following the branch/tag conventions for the specific release.
5. Add a link of this new /doc/5-5-0 into online documentation index openacs.org/doc and a map it in the site map to /doc/current

Then the process can start again for the next documentation release.

To-Do

• Still missing a way to transform to independent html files with index / navigation within it (right now only produces a one big html). (done by Gustaf)
• New /doc has to have a link to the various online (xowiki) frozen versions of the documentation.
• Document the document formatting/markup rules in the wiki instance and the static documentation. 
  • Probably there is already formats for technical documentation available, produced, or at least some guidelines.
• Openacs.org/doc will be replaced with the wiki-documentation (/test-doc instance renamed to /doc/head)
  • Provide an index to link to all frozen documentation releases.
  • Current /doc can be renamed to /doc-5-1
• Assign someone to udpate the documentation, follow the process and release documentation.

Following moved to this context, which is using approach discussed by Malte below:

Malte here:

Instead of doing it manually (though this does have some merit), I would go and modify the script Gustaf provided to import the whole documentation in one go into a new XoWIKI instance with the structure (page_order) that has been added in XoWIKI 0.42 taken from the chapters of the documentation so that we do have an exact mirror of the documentation as it stands now.

Once this is achieved we could go on and assign categories to the documentation, allowing for an alternative view on the documents (so you could say "instead of showing the whole documentation only show the documents for a specific category"). Probably this needs some more detailed discussion with Gustaf finding out how this could be achieved in XoWIKI and what would make most sense. Ideally we could provide a different structure based on the target group (e.g. category) but this is probably shooting too far. Getting categorization and page ordering in a decent shape should provide us a lot of possibilities.

• One can use the follwing script to generate the page objects and load it via xowiki/admin/import into an xowiki instance; this can be improved in many places, but gives you the idea
• # by Gustaf Neumann 
• # load doc pages into xowiki   -gustaf neumann
  # for tdom
  lappend auto_path /usr/local/aolserver4/lib
  package require tdom
  package require XOTcl; namespace import ::xotcl::*
  package require xotcl::serializer
  
  set docpath /usr/local/openacs-4/packages/acs-core-docs/www/
  
  namespace eval ::xowiki {
    Class create Page -parameter { {lang en} {description ""} {text ""}
      {nls_language en_US} {mime_type text/html} name title text }
  
    set c 0
    foreach docpage [glob $docpath/*.html] {
      set f [open $docpage r]; set data [read $f]; close $f
      dom parse -html $data doc
      $doc documentElement root
  
      set content ""
      foreach n [$root selectNodes //body/*] { append content [$n asHTML] \n }
   
      set p [Page create page[incr c] -name en:[file tail $docpage] \
             -title [[$root selectNodes //title] asText] \
             -text [list $content text/html]]
      puts [::Serializer deepSerialize $p]
    }
  }

Suggestion by Rob Taylor: 

1a. Move all but maybe the first and last 2 items from https://openacs.org/doc/dev-guide.html to https://openacs.org/doc/kernel/dev-guide.html and refer to them in context of the kernel package (or whatever package their code is in). That helps developers see appropriate context. (This will likely require a board discussion and TIP