[oi-dev] Fwd: [OpenIndiana-discuss] Documentation-Project

Mon May 30 18:49:26 UTC 2011

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 <kgunders at teamcool.net> 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
> oi-dev at openindiana.org
> http://openindiana.org/mailman/listinfo/oi-dev
>

-- 

Jabber:	boti at jabber.ccc.de
ICQ: 	279837014
Handy:	0178-5545505
Skype:	grund-rauschen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: uni.vcf
Type: text/x-vcard
Size: 121 bytes
Desc: not available
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110530/d67f8058/attachment-0005.vcf>