###    
   ##    
   ##    
   ##    
   ##    
   ##    
  ####   
         

 _   _ 
( ) ( )
| | | |
| | | |
| (_) |
(_____)
       
       

 _   _ 
| \ | |
|  \| |
| . ` |
| |\  |
\_| \_/
       
       

         
         
  ####   
 ##  ##  
 ######  
 ##      
  #####  
         

 _     
( )    
| |    
| |  _ 
| |_( )
(____/'
       
       

IMPORTANT: enter the case-INsensitive alphabetic (no numbers) code AND WRITE SOME SHORT summary of changes (below) if you are saving changes. (not required for previewing changes). Wiki-spamming is not tolerated, will be removed, so it does NOT even show up in history. Spammers go away now.


Visit Preferences to set your user name
Summary of change:
'''This page was about finding a better way of maintaining and presenting the GenBoard/Manual''' '''the XML manual is maintainer-friendly now: our excuses are gone''' - the framework is ready for our real manual work. These days mostly MembersPage/Phatbob, MembersPage/EsbenNorby and MembersPage/JimW work on it, feel free to join them. You can write any plans, questions here (or anywhere, and link from here). It is also common (but not a requirement) to join irc ( ChatViaIrc ) when working on the manual. The manual in '''CVS is obsolete'''. <code> export CVSROOT=:ext:<your sourceforge username>@cvs.sourceforge.net:/cvsroot/megasquirtavr </code> '''The new storage location of the manual is''' <code> svn co https://svn.x-dsl.hu/svn/manual </code> See SubVersionSvn (instead of GenBoard/FirmWare/CVSUsage). ---- '''Generating HTML files''' - running xsltproc Since sourceforge does not support crontab (and we had problems with the cgi based workaround), the new place for generating files is http://www.vems.hu/manual/html/ Unfortunately the links in wiki still point to sourceforge, we can try one of: * cure the CGI wrapper, so we can trigger sourceforge from a distant wget to generate the manual. I prefer this, having 2 instances of the generated manual seems to be little overhead with some gains. Might just take changing ''system("/home/groups/m/me/megasquirtavr/bin/daily_snapshot.sh");'' to an exec() function. * s/oldURL/newURL/ ** tweak wiki engine (php) ** tweak wiki mysql database ** tweak wiki mysql database dump sql-text (that is to be loaded back of course) I tried to update the sourceforge html manual, no luck so far: * the http://vems.hu/manual/ uses different html filenames, http://vems.hu/manual/html/ch09.html instead of http://megasquirtavr.sourceforge.net/manualhtml/Detailed.Sensor.RPM.html * on sourceforge, /home/users/m/ma/marcell/megasquirtavr I copied ** manual dir (the dir with the generated html from the vems.hu server) - svn tree should do * edited bin/generate_html_manual.sh , similar to bin/daily_snapshot.sh but without checking out from CVS. Checking out from SVN should work too, ** but first it should be able to generate HTML with proper filenames. Should be simple to solve, with some more attention. ---- Do not use Morphon or other WYSIWYG XML editors. Contact one of the maintainers or use a simple text editor and send diffs for reviewing. Now the '''XML manual is as easy to work with''' as word: http://www.vems.hu/files/Manual/Construction/morphon.png but without the serious maintenance (locking, diffing, efficient storage of revisions) and presentation problems of the previous MS Word doc format. Note that the tree-browsing view on the left shows the proper names (id-s) of sections now. There are some guidelines in CVS manual/design/guidelines.txt but nothing too complex. In any case, ask for help here or ListsAndForums genboard-dev list if you have problems. * [http://www.morphon.com/ Morphon] and [http://www.morphon.com/cgi-bin/shop/free-register.cgi?cont_url=/download/download2.html Morphon XML editor free download] I edited a few lines of the manual in Morphon. * first Morphon complained about syntax * the diff became huge, 7429 lines (with -U3). Mostly removed linebreaks (that were added for readibility, I assume?), but who knows ? I didn't dare to commit it, I applied it again (it's mostly about EC36pin28 for the HALL supply +5V, rev172) What is the recommended method for editing ? Should we make it Morphon compatible or it does not worth the effort ? ---- '''XML manual''' Frank, Richb and Peter prepared the manual for docbook. Stored in the manual module in sourceforge megasquirtavr CVS. Now the manual itself is in manual.xml file, (started the split-files approach, but reverted: this is now moved to oldmanual directory ), but there are directories for images, issues, decisions, design/guidelines, etc... Generated HTML manual is getting useful for human consumption. Errors that should be corrected by now: * formatting is broken (many wiki text copypasted without taking care about formatting). Check wt2db experiments below. * pages unified: not possible to link into a small paragraph (eg. when making index for something) * many broken links If you think you can help fix either (maybe just running xsltproc command with the right arguments on sourceforge) please help. Note that everyone with RW access to CVS * has ssh access to shell.sourceforge.net with his username/pw * take care about permissions: everything should be read-writable by anyone in the megasquirtavr group (chmod -R g+rw dir) '''The rest of this page is not uptodate, only brainstorming or superseeded by manual/design/guidelines and manual/README''' ---- '''wt2db wiki => XML converter''' Maybe [http://www.tldp.org/downloads/ wiki text => docbook] and particularly http://www.tldp.org/downloads/wt2db-1.0.tar.gz is to our rescue. But I guess we'll have to run it manually on small fragments during to transfer process, and copy the result to the right manual chapter. [http://www.vems.hu/files/Manual/Construction/manual-frag.tgz files of Marcell's experiments] * manual.xml (mixed wiki and XML) * removed XML tags (manually) * wt2db -x manual-frag.wtx >manual-frag.xml This has been used for conversion. Helped a lot, but work was needed after. Eg. bullet lists seem OK, but tables NOT. ---- How about [http://www.hieraki.org/ Hieraki]? Combines Wiki with a hierarchy of a real book. Under development; so it can only export to a metadata format right now, but will def. support pdf in the future. [http://rails.hieraki.org/ Here] is an example of how it can look. ---- '''Filtering''' obsoleted by utilizin a docbook tag: <code> <simpara conformance="v3.1 v3.2">...</simpara> </code> * show in example how '''information relevance'' can be tagged. This info is used to filter confusing sections at generation-time, eg. by given key-value pairs. This functionality is '''very important'''. If we don't have this, and relevance info is loaded on the head of the enduser (if you have v3.0 than .... otherwise ... zzzz ) and maintenance info is kept separated, there is no reason to use XML (because than there would be more disadvantages than advantages compared to wiki). Relevancy must be simple like: ** <relevant key="board_version" op="greater" value="3.1" > (gets filtered for someone having v3.0) ** <relevant key="maintanance_level" op="greater" value="2" > (gets filtered for normal users that read the manual, not maintain it). We're looking at adding a [http://www.oasis-open.org/docbook/documentation/reference/html/ch05.html customization layer] for this. This means a DTD so we can validate documents, and more work on our custom XSLT to pre-transform to !DocBook. Basic output generation process is "our format" -> parse and validate -> Genboard specific !DocBook -> HTML / PDF / etc. Should be managable, but we should document it here before implementing anything much. Many tags like <todo> and <genboard version=""> would be harder to maintain: the dtd and the filtering must be edited and distributed each time (distribution would work with CVS, I guess). While that's doable, we should use separate tag only for the most common characteristics and use a common tag (like the relevant above) with keys to prepare for several characteristics. I expect 15..30 keys in the mid-term (all will have default values, so the end-user shouldn't care at all: but we need it). To do this properly the attribute keys should be in an Enumeration (as opposed to PCDATA), which lives in a DTD so needs to be edited when keys are changed. The XSL also needs to be edited to handle the attributes and keys so the transforms can work properly. Reducing the number of tags is a good thing however. <relevant> tags and similar are beginning to look like hard work to integrate with !DocBook, unless we decide to limit where they can be used. A "go anywhere" answer is defining local attributes. We can add vems_version, vems_maintainence, vems_feature to the list of common attributes, and this lets us put them anywhere. It's then easy to block out paragraphs, sections, lists, etc. Basic filtering of the WBO2 section works, but it's still in the TOC for some reason. As as example, this was done with <section vems_feature="wbo2">. wbo2 is defined in an enumeration in vems.dtd. To filter the output, the vems_html.xsl file imports vems_filtering.xsl in addition to chunk.xsl. Note that this will finally make it possible for the end-user to click his basic setup (on a web-page) and have a customized, slim version of the manual that doesn't even contain stepper-idle sections if he configured solenoid idle. This is the main benefit from going XML. ---- '''Split the manual to several files''' - eg. sect1 Mainly to ease CVS difference look at task/0011 Splitting XML sources like this is usually done with [http://www.w3.org/TR/xinclude/ XInclude]. Morphon + the built-in Saxon XML processor isn't too smart here, so we just assemble for editing. In theory, we can use Java 1.4 / 1.5, jaxp.properties, and Xerces-J + Saxon to make this happen automagically: ** http://www.sagehill.net/docbookxsl/Xinclude.html ** http://lists.oasis-open.org/archives/docbook-apps/200310/msg00348.html In reality, it doesn't work nicely with Morphon and JAXP. Bugs either break things during XLST, or Morphon complains about Xerces version. Have tried other transformers too, without success. Where that leaves us is using Morphon to create individual chapters or sections, and either preprocessing with xincluder or using something like xsltproc to do the whole XSLT process outside of Morphon. No big deal as the editing still happens in an easy to use GUI. * We must be able to '''link into sections''' (of '''a generated html tree''') easily. With minimal risk of breaking the link (say when chapter title changes) later. It isn't a Wiki, but it is doable - [http://www.docbook.org/tdg/en/html/xref.html xref] tag can be used for this. ---- '''Generic advice''' * split newbie and developer info (developer info doesn't go to the XML manual) * keep information max 1 click from main index (such as GenBoard/Manual matrix) * '''matrix''' as on '''GenBoard/Manual''' helps position (and find) information and define the scope of a writing ** the matrix helps everyone to find information ** the matrix helps maintainers to split information ** the matrix helps to check completeness * so the XML manual must be prepared with the matrix in mind: we must be able to refer to sections of the generated XML=>HTML manual from the matrix. * at least first (header) line and column in the matrix could have small image icons * '''the average user is not interested in how the internals work'''. Not in the processor, and not in event handling details. * However '''explaining the fuel calculations and trigger processing is very important'''. * It is also '''HIGHLY RECOMMENDED that you search existing wiki pages''' so that you dont rewrite something that is already written and can just be cleaned up or added to. * '''Move''' (not copy) info (but leave correct, not broken links behind) * Make sure that we do not just copy/paste from another source, but rather reword to prevent copyright or plagiarism problems. * '''Please also add a link back to the GenBoard/Manual page on the new page''' * keep it to '''instructions only'''. If you have personal experiences or advise, tag as "User Notes" (?). This will come in handy when creating the PDF file as we will have side boxes which will host these user notes. ---- '''Formatting possibilities''' With some work and proper usage of tags either wiki or XML can be parsed and presented as * HTML (for the Wiki) note: http://csszengarden.com/ might be useful * PDF (for printing) * YAML (for my configuration program) * anything else (for everyone elses configuration programs) I'm no lover of XML (just thinking about it makes my wrists hurt) but there must be some meta format that can be used to encapsulate the data and yet provide easy access for everyone? I have a [http://platina.sytes.net/repos/GenBoardConfig/configConfig.yaml example] of how it looks in YAML. Not saying that this is the best format; but it's a example of a easily parsable, extendable metaformat. Maybe the wiki should have a plugin so any page could be maintained in XML, and still presented as if it was wiki format. That would allow editing via web, and using advanced tools too.
Optional: Add document to category:
Wiki formatting: * is Bullet list ** Bullet list subentry ... '''Bold''', ---- is horizontal ruler, <code> preformatted text... </code> See wiki editing HELP for tables and other formatting tips and tricks.