[Doc-SIG] Python docs in reST
Felix Wiemann
Felix.Wiemann at gmx.net
Fri May 27 19:03:54 CEST 2005
Martin Blais wrote:
> Michael Foord wrote:
>
>> Felix Wiemann wrote:
>>
>>> Ideas:
>>>
>>> * We want to have **well-readable** documentation source.
>
> hmmm... the current latex markup is as simple as it can be. it's got
> a word, and some form of delimiters, e.g. \function{foo}. i don't
> feel that `foo`:function: is all that much better.
No, indeed not. However, there are other differences I outlined in
<http://article.gmane.org/gmane.comp.python.documentation/947>.
> rest allows you to view the input files directly, as output (ascii
> output = input). this assumes that the markup is kept to its *bare
> minimum*. this is an *explicit* reason for creating rest in the first
> place. the more we are talking about adding markup on rest, the
> stranger this whole discussion is becoming.
First of all, just to avoid misunderstandings, I don't think roles like
:function: or :class: will be added to standard-reST. If it all, it
will be an extension (possibly shipped with the Docutils distribution
though) which must be explicitly activated (probably from inside the
reST document, like ".. extension:: python-doc").
While the goal of reST is to avoid explicit markup, IMO it's fine to use
explicit markup where considered necessary and it doesn't make reST less
useful.
> [...] with rest, the source has to more or less "look like" the
> output.
That's a goal, but it's not a requirement: You can still use reST if the
output doesn't look exactly like the reST source.
And even if you mark up function names, parameters and class names,
still a lot of reST's WYSIWYG and simplicity is retained, and that's a
big advantage over LaTeX.
> IMHO the worst thing that could happen is that one day I open a text
> file supposedly writtne in rest, and that i can't understand it
> because i have to learn what all that new markup is all about.
As I wrote above, all that explicit markup won't be part of
standard-reST.
--
For private mail please ensure that the header contains 'Felix Wiemann'.
http://www.ososo.de/
More information about the Doc-SIG
mailing list