On Thu, Feb 24, 2011 at 10:11:28AM -0500, Gaetan Nadon wrote: > On Thu, 2011-02-24 at 15:22 +1000, Peter Hutterer wrote: > > > not having to write or look at roff syntax is an added benefit :) > > > > Indeed, the syntax is intimidating. > > Yet another alternative is DocBook/XML which directly supports man > pages. > This would save the step going from asciddoc to docbook and then from > docbook to man pages. > > The man pages (in xml format) could be viewed directly in the > desktop help browser, gnome-help for example. > > This is more appealing to wacom than it is to xorg, as wacom is a linux > only project where free XML editors are available such as XMLmind. > Of course, typing xml is no better than typing roff, so the editor > would be a deciding factor. > > http://www.xmlmind.com/xmleditor/ > > Finding a balance between ease of use and ease of maintenance > is never easy.
I've learned one lesson in the last couple of years: the easier you make it to write documentation, the more likely you'll have _any_ documentation. (unless you pay people of course. some people will even write roff for money ;) I had a short affair with xml during the XI2 development cycle but it was painful. so many tags, it makes it really hard to proof-read anything and harder to edit. plus, the bit of documentation we have in the driver is very simple - two man pages. docbook seems a bit overkill here. Cheers, Peter ------------------------------------------------------------------------------ Free Software Download: Index, Search & Analyze Logs and other IT data in Real-Time with Splunk. Collect, index and harness all the fast moving IT data generated by your applications, servers and devices whether physical, virtual or in the cloud. Deliver compliance at lower cost and gain new business insights. http://p.sf.net/sfu/splunk-dev2dev _______________________________________________ Linuxwacom-devel mailing list Linuxwacom-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/linuxwacom-devel
