Re: [Linuxwacom-devel] asciidoc wacom man page (was Re: Sample xsetwacom scripts vetting)
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
Re: [Linuxwacom-devel] asciidoc wacom man page (was Re: Sample xsetwacom scripts vetting)
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. signature.asc Description: This is a digitally signed message part -- 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
Re: [Linuxwacom-devel] asciidoc wacom man page (was Re: Sample xsetwacom scripts vetting)
On Wed, Feb 23, 2011 at 11:11:34PM -0600, Chris Bagwell wrote: > On Wed, Feb 23, 2011 at 10:24 PM, Peter Hutterer > wrote: > > On Thu, Feb 24, 2011 at 02:18:10PM +1000, Peter Hutterer wrote: > >> > So we want the user to read man wacom, xsetwacom, xinput and then > >> > assemble their own script combining xsetwacom and xinput? I agree > >> > >> mind you, the whole point of xsetwacom is that users don't need xinput. I > >> still expect them to read the wacom man page so they understand what > >> they're > >> changing though. > > > > slight topic change. for some reason, man pages have a bad reputation. I'm > > not sure why though. > > > > One thing that may help here is a switch to asciidoc for the man page. the > > biggest benefit here is that the man page is a simple text file that we can > > link to. and you can link to the latest version in git of it directly and > > anyone can read it. example: > > http://cgit.freedesktop.org/evtest/plain/evtest.txt > > > > the actual conversion to groff format is done during the build process. > > > > drawback - less formatting styles (though asciidoc may provide more than I > > currently know) and another dependency (which already exists for plenty > > other packages though, e.g libXi) > > > > Are you suggesting because more people may be willing to edit a text > file than a man page? Or are you interested in the multiple outputs? I'm mostly interested in the - "our current man page is here: linuxwacom.git.sourceforge.net/blah/blah/xsetwacom.txt" not having to write or look at roff syntax is an added benefit :) Cheers, Peter > If the later: > > I've had good luck with maintaining docs in man format but then add > following rules in Makefile to be used during release process. People > do seem to respond positively to reading txt/html/pdf over man > pages... and don't really know they are derived from man pages. > > For dependencies, every platform with man will have nroff to generate > txt file and for html/pdf part it just requires gnu groff+ghostscript. > wacom is not using tables so no need for the "tbl" or -t options. > > .1.txt .3.txt .7.txt: > tbl $(srcdir)/$< | nroff -man -c > $@ > > .1.pdf .3.pdf .7.pdf: > pdfroff -t -man -Tps $(srcdir)/$< > $@ > > .1.html .3.html .7.html: > groff -t -man -Thtml $(srcdir)/$< > $@ > > Chris > -- 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
Re: [Linuxwacom-devel] asciidoc wacom man page (was Re: Sample xsetwacom scripts vetting)
On Wed, Feb 23, 2011 at 10:24 PM, Peter Hutterer wrote: > On Thu, Feb 24, 2011 at 02:18:10PM +1000, Peter Hutterer wrote: >> > So we want the user to read man wacom, xsetwacom, xinput and then >> > assemble their own script combining xsetwacom and xinput? I agree >> >> mind you, the whole point of xsetwacom is that users don't need xinput. I >> still expect them to read the wacom man page so they understand what they're >> changing though. > > slight topic change. for some reason, man pages have a bad reputation. I'm > not sure why though. > > One thing that may help here is a switch to asciidoc for the man page. the > biggest benefit here is that the man page is a simple text file that we can > link to. and you can link to the latest version in git of it directly and > anyone can read it. example: > http://cgit.freedesktop.org/evtest/plain/evtest.txt > > the actual conversion to groff format is done during the build process. > > drawback - less formatting styles (though asciidoc may provide more than I > currently know) and another dependency (which already exists for plenty > other packages though, e.g libXi) > Are you suggesting because more people may be willing to edit a text file than a man page? Or are you interested in the multiple outputs? If the later: I've had good luck with maintaining docs in man format but then add following rules in Makefile to be used during release process. People do seem to respond positively to reading txt/html/pdf over man pages... and don't really know they are derived from man pages. For dependencies, every platform with man will have nroff to generate txt file and for html/pdf part it just requires gnu groff+ghostscript. wacom is not using tables so no need for the "tbl" or -t options. .1.txt .3.txt .7.txt: tbl $(srcdir)/$< | nroff -man -c > $@ .1.pdf .3.pdf .7.pdf: pdfroff -t -man -Tps $(srcdir)/$< > $@ .1.html .3.html .7.html: groff -t -man -Thtml $(srcdir)/$< > $@ Chris -- 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
