Hi all, I thought that Sphinx is better known in the Open-Source-Community, but because it's not known by the most of you, it might be easier for you, if I explain it shortly. Sphinx [1] was original written to write the Python-documentation and it is written in Python itself, so it runs on any platform on which python 2.6 runs. Nowadays it is widely used, especially by python-projects like Zope, Django, Bazaar and also by Blender for example and it is actively developed.
The software itselfs uses reStructuredText which is very close to metawiki-syntax or especially Markdown. It is build modular and generates HTML, Gnome- and Windows-Help, man-pages, PDFs and Latex automatically and is easy to expand. It is also possible to add mathematically formulars, source-code and complete API-descriptions. To get an impression of the syntax, you can click on the "show source" link in the python or sphinx-docu. As I read, there is also a converter from DocBook to reStructuredText available, so a converter(or in Sphinx called Generator) to DocBook might not be an unsolvable problem. In my opinion, I prefer reStructuredText over DocBook and Latex, because it is very easy to write with standard-editors(like vim, emacs, ... in some with syntax-highlighting, this is true for Latex either) but much easier to learn. It is also easy to manage with Mercurial or Git and build with hooks or simple Makefiles (of course automatically to all formats). If you prefer to use pure DocBook or Latex, it is of course ok for me. I used Latex some times till now, mostly in university for math. Tobias [1] Sphinx-page: http://sphinx.pocoo.org/ Python-Documentation for example: http://docs.python.org/py3k/ Page for reading the documentations easily: http://readthedocs.org/ Am 30.05.2011 19:07, schrieb Ken Gunderson: > On Mon, 2011-05-30 at 11:23 -0500, TJ Yang wrote: >> On Mon, May 30, 2011 at 10:49 AM, Ken Gunderson <[email protected]> >> wrote: >>> On Mon, 2011-05-30 at 08:24 +0400, Garrett D'Amore wrote: >>>> Switching to another less popular doc format doesn't seem like a great >>>> idea. I don't work with the documentation frequently, but I'd ask people >>>> that do. >>>> >>>> One thing is that some of these formats are like fads... they come and go. >>>> I remember not long ago when SGML was all the rage. :-) From my >>>> perspective it would be good to have a format that has good tools >>>> available (multiple implementations, at least some of which are portable >>>> to other platforms), displays nicely, and provides some basic structure >>>> capabitilities to assist in parsing for content or format conversion (e.g. >>>> to HTML). >>>> >>>> If you make me install a bunch of new tools, or learn a format that nobody >>>> else uses, I probably will be less inclined to write documentation. (That >>>> said, I've not written much except a few man pages, and the format of >>>> *those* is relatively constrained by the need to be able to display them >>>> with the man command. :-) >>>> >>>> -- Garrett D'Amore >>> I would think Docbook would be the way to go. Yeah, it's going to >>> require some specific libraries and tools but it's transformable to many >>> different formats. I haven't dealt with it for a while now but easily >>> to morph to man, text, html, and pdf, which I think pretty much covers >>> all reasonable bases. >>> >>> XML situps are a pain after the first few thousand. Last I looked most >>> good XML editors out there were proprietary. All fine and dandy if >>> you're a commercial corp with a documentation staff but such would seem >>> to raise the bar w/o much of any real gain for a small FOSS project. >>> >>> Else maybe the old standard Latex, wh/facilitates same, and although out >>> of vogue at present, I don't think it's not going to disappear anytime >>> soon. Advantage here might be that lots of science and math types will >>> already be somewhat familiar w/it from thesis writing and such, but I'd >>> also think this would not encompass a significant number of OS/IllumOS >>> contributors. >> Hi, All >> >> This is my personal experience on this matter. >> >> Having use both Docbook and LaTeX to on a few manuals before. >> I actually retracted back to use LaTeX from docbook as documentation >> tools to create Manual/Book. >> >> >>> I've never heard of Sphinx. >> Me either. >> >> So to me, Docbook is acceptable but LaTeX is the best tool, IMHO. >> >> tj > Interesting. Plus added advantage that's it's going to be easy access > via emacs, wh/is readily available for pretty much any platform. Yeah, > docbook is going to be too, but goes to show you that sometime old > school tools are old school because they're the best tools.... > > > _______________________________________________ > oi-dev mailing list > [email protected] > http://openindiana.org/mailman/listinfo/oi-dev > -- Jabber: [email protected] ICQ: 279837014 Handy: 0178-5545505 Skype: grund-rauschen
<<attachment: uni.vcf>>
_______________________________________________ oi-dev mailing list [email protected] http://openindiana.org/mailman/listinfo/oi-dev
