VEMS Home Products Documentation Wiki Webstore
WikiHome ProjectPage DocsPage UnderDevelopment MembersPage SiteIndex RecentChanges Preferences
GenBoard/ManualConstruction (2006-03-16 04:43:08)

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

We are migrating to the XML manual that is stored in CVS.

Now the XML manual is as easy to work with as word:

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 manual/design/guidelines.txt but nothing too complex.

In any case, ask for help here or ListsAndForums genboard-dev list if you have problems.

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:

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

The rest of this page is not uptodate, only brainstorming or superseeded by manual/design/guidelines and manual/README

wt2db wiki => XML converter

Maybe [wiki text => docbook] and particularly http://www.tldp.org/downloads/wt2db-1.0.tar.gz is to our rescue. But I guess we still have to run it manually a few hundred times and copy the result to the right manual chapter.

[files of Marcell's experiments]

bullet lists seem OK, but tables NOT.

Can some one comment on the quality of result XML ?

How about [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. [Here] is an example of how it can look.

GenBoard/Manual - in wiki

Improvement Options:

Filtering

obsoleted by utilizin a docbook tag:\nÿ1ÿ

We're looking at adding a [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 [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:

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.

It isn't a Wiki, but it is doable - [xref] tag can be used for this.

Generic advice

Formatting possibilities

With some work and proper usage of tags either wiki or XML can be parsed and presented as

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 [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.

Additional Notes

Add notes about the content of the manual