Re: [Python-Dev] status of development documentation

classic Classic list List threaded Threaded
19 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] status of development documentation

Fred Drake-3
[Copied to the Doc-SIG list.]

On Wednesday 21 December 2005 13:02, Josiah Carlson wrote:
 > +1 for using ReST.
 > +0 for sticking with latex.

I'll try and spend a little time on this issue this week, but time is hard to
come by these days.

ReST (as implemented in docutils) at this point does *not* support nested
markup constructs, unless something has changed in the last few months.  I
think this is a significant limitation.

LaTeX, for all the tool requirements, is a fairly light-weight markup
language.  Yes, it has too many special characters.  But someone else
invented it, and I'm not keen on inventing any more than we have to.

There is the matter of all the semantic markup we're doing in the LaTeX
sources; some people think it's fine, and others think using a specialized
semantic markup is either a bad idea or at the least a barrier to
contributions (though I've pointed out that contributing just plain text is
fine many, many times).  Alternatives to the semantic markup that I expect to
see suggested include:

nothing special, just using presentation markup directly:
  This prevents even simple information re-use.  Conventions can help, but
  require a careful eye on the part of editors (possibly with tools to help).

something like HTML, but with "microformat" style annotations:
  More reasonable, especially if we rely on conventions and stylesheets for
  presentation.  I expect the markup will actually be much heavier than the
  current markup, though it will be somewhat more familiar to someone when
  they first look at it.  Adding in the annotations changes that a bit.

docbook, because others use that:
  This is really heavy, but tools exist.  The last I looked at the OOP
  extensions, they were fairly simple, but not well matched to Python.

ReST, possibly with additional interpreted text roles:
  This has been explored in the past, and would likely not be a bad approach.
  As noted above, I expect non-support for nested markup in docutils to be a
  problem that will become evident fairly quickly.

All that said, I think this discussion belongs on the Doc-SIG; I've CC'd that
list.


  -Fred

--
Fred L. Drake, Jr.   <fdrake at acm.org>
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] status of development documentation

Fredrik Lundh
Fred L. Drake, Jr. wrote:

> LaTeX, for all the tool requirements, is a fairly light-weight markup
> language.  Yes, it has too many special characters.  But someone else
> invented it, and I'm not keen on inventing any more than we have to.

"someone else invented it" is of course why I'm advocating an HTML-
based format.  There's a huge infrastructure, both on the tool side and
on the spec side, that deals with (X)HTML.  And *everyone* knows
how to write HTML.

> nothing special, just using presentation markup directly:
>   This prevents even simple information re-use.  Conventions can help, but
>   require a careful eye on the part of editors (possibly with tools to help).
>
> something like HTML, but with "microformat" style annotations:
>   More reasonable, especially if we rely on conventions and stylesheets for
>   presentation.  I expect the markup will actually be much heavier than the
>   current markup, though it will be somewhat more familiar to someone when
>   they first look at it.  Adding in the annotations changes that a bit.

Light annotations plus simple conventions (with corresponding simple tools)
should be more than good enough to match the current level.

> docbook, because others use that:
>   This is really heavy, but tools exist.  The last I looked at the OOP
>   extensions, they were fairly simple, but not well matched to Python.
>
> ReST, possibly with additional interpreted text roles:
>   This has been explored in the past, and would likely not be a bad approach.
>   As noted above, I expect non-support for nested markup in docutils to be a
>   problem that will become evident fairly quickly.
>
> All that said, I think this discussion belongs on the Doc-SIG; I've CC'd that
> list.

The doc-sig didn't look too active when I checked the archives, but maybe
it's time to change that.

</F>



_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] status of development documentation

Skip Montanaro-3

    Fredrik> "someone else invented it" is of course why I'm advocating an
    Fredrik> HTML- based format.

Of course, someone also invented HTML and TeX+LaTeX predates HTML by quite a
bit.

    Fredrik> And *everyone* knows how to write HTML.

That's debatable.  Maybe most people in the python-dev community know how.
Even within this communitiy I suspect there are at least a few people who
normally use something else (like Word) to generate HTML for them.  I
suspect to use the microformat stuff you'd have to restrict your authoring
toolchain substantially, perhaps restricting it to plain old text editors.

Skip
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] status of development documentation

ianb
[hidden email] wrote:
>     Fredrik> And *everyone* knows how to write HTML.
>
> That's debatable.  Maybe most people in the python-dev community know how.
> Even within this communitiy I suspect there are at least a few people who
> normally use something else (like Word) to generate HTML for them.  I
> suspect to use the microformat stuff you'd have to restrict your authoring
> toolchain substantially, perhaps restricting it to plain old text editors.

If we were using a microformat, it is likely that the CSS class would be
used to mark content.  At least that's what I've noticed in some recent
microformat specs, and there's lots of good reasons to follow that.
Tool support for adding classes to elements is relatively good; not
great from what I can tell, but good.  Not that I use a lot of these
editing tools, so I might be wrong.

Still, the output of WYSIWYG tools remains very poor.  Because not
everyone will be using WYSIWYG tools, it is likely that any such output
will be to be cleaned -- reindented, and probably with any unrecognized
styling removed.  But this isn't that hard.

Also, I assume that most documentation maintainers will continue to use
text editors, because programmers use text editors, and this is
programer documentation.  I think it is very reasonable to expect people
to know HTML; I find it unlikely that many people will enjoy authoring
HTML.  I know HTML quite well, I continue to write lots of it, and I've
never enjoyed writing programming documentation in HTML.  I guess in
practice I write very little HTML *content*, just structure, and when
I'm writing structure I don't mind the markup.  But when I want to focus
on content the markup is very distracting, and even moreso when writing
about programming (where ASCII, newlines, and whitespace is the native
layout technique).

To me, using HTML feels like sacrificing the authoring experience for
expedient tools.  This doesn't seem like a big step forward from LaTeX.

--
Ian Bicking  /  [hidden email]  /  http://blog.ianbicking.org
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] status of development documentation

PJ Eby
At 01:43 PM 12/21/2005 -0600, Ian Bicking wrote:
>  But when I want to focus
>on content the markup is very distracting, and even moreso when writing
>about programming (where ASCII, newlines, and whitespace is the native
>layout technique).

And where characters like '<' and '>' occur frequently as part of the text,
especially in showing Python interactions like this:

     >>> print "hello world"
     hello world

I can't imagine trying to author the above in an HTML/XML based format,
whereas in reST (or even LaTeX) I can just copy and paste it from an
interpreter window.

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] status of development documentation

Laura Creighton
In reply to this post by ianb

Whenever people have demanded that I write documentation in html
I have always done this:

<pre>
all my documentation, as output from a text editor.

All subsequent formatting to be done by somebody else who doesn't
find dealing with html as excruciatingly painful as I do.
</pre>

I suspect there are lots of people who have concluded that this
is all the html that you really need.  The question is, are you
willing to put up with documentation like this from people?

Laura
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] status of development documentation

Steve Holden-5
Laura Creighton wrote:

> Whenever people have demanded that I write documentation in html
> I have always done this:
>
> <pre>
> all my documentation, as output from a text editor.
>
> All subsequent formatting to be done by somebody else who doesn't
> find dealing with html as excruciatingly painful as I do.
> </pre>
>
> I suspect there are lots of people who have concluded that this
> is all the html that you really need.  The question is, are you
> willing to put up with documentation like this from people?
>
Well the existing system can cope with that style, but for some reason
the oft-repeated advice that plain text markup is an acceptable format
for documentation contributions doesn't seem to have escaped the gravity
field. So that's just as good for the existing docs as anything that
replaces them (if anything does).

regards
  Steve
--
Steve Holden       +44 150 684 7255  +1 800 494 3119
Holden Web LLC                     www.holdenweb.com
PyCon TX 2006                  www.python.org/pycon/

_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] status of development documentation

Fredrik Lundh
In reply to this post by PJ Eby
Phillip J. Eby wrote:

> And where characters like '<' and '>' occur frequently as part of the text,
> especially in showing Python interactions like this:
>
>      >>> print "hello world"
>      hello world
>
> I can't imagine trying to author the above in an HTML/XML based format,

it's spelled

    >>> print "hello world"
    hello world

in HTML.

</F>



_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] status of development documentation

ianb
In reply to this post by Fred Drake-3
Fredrik Lundh wrote:

>>Maybe it's just because I came in late on this thread, but what exactly
>>is broken about the current LaTeX documentation?
>
>
> Checked the python-list archives lately?  If you google c.l.python for the
> word "documentation", you'll find recent megathreads with subjects like
> "bitching about the documentation", "opensource documentation problems"
> and "python documentation should be better" among the top hits.  But if
> you check the bug and patch trackers, you don't find many contributions.
> Something's definitely broken.

This is somewhat tangential to this discussion, but I did have the
Python documentation in mind as a potential future target for
Commentary: http://pythonpaste.org/comment/commentary/ -- which would
allow more casual contributions that seem to work well for other projects.

--
Ian Bicking  |  [hidden email]  |  http://blog.ianbicking.org
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] status of development documentation

Michael Foord
In reply to this post by Steve Holden-5
Steve Holden wrote:

> Laura Creighton wrote:
>
>>Whenever people have demanded that I write documentation in html
>>I have always done this:
>>
>><pre>
>>all my documentation, as output from a text editor.
>>
>>All subsequent formatting to be done by somebody else who doesn't
>>find dealing with html as excruciatingly painful as I do.
>></pre>
>>
>>I suspect there are lots of people who have concluded that this
>>is all the html that you really need.  The question is, are you
>>willing to put up with documentation like this from people?
>>
>
> Well the existing system can cope with that style, but for some reason
> the oft-repeated advice that plain text markup is an acceptable format
> for documentation contributions doesn't seem to have escaped the gravity
> field. So that's just as good for the existing docs as anything that
> replaces them (if anything does).

Hmmm... I submitted some plain text (might have been reST actually) docs
as a suggested addition to urllib2. The response from the maintainer)
was that I ought to submit it as patches against the original Tex document.

Now admittedly what I submitted *does* need breaking into smaller
sections to make it easier to add to fit into the docs. (IIRC the error
classes are barely documented in urllib2 - vital information is missing
from the docs).

*However* - there was no implication that the maintainer was happy to
work with plain text submissions.

All the best,

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml

> regards
>   Steve

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] status of development documentation

Fredrik Lundh
In reply to this post by ianb
Ian Bicking wrote:

> This is somewhat tangential to this discussion, but I did have the
> Python documentation in mind as a potential future target for
> Commentary: http://pythonpaste.org/comment/commentary/ -- which would
> allow more casual contributions that seem to work well for other projects.

indeed.

Commentary worked better this time than last time I tinkered with it.  a few
notes:

- it would be nice to be able to cancel a new note by double-clicking again
in the same spot (at least as long as the note is empty)

- IE support seems to be a little shaky; klicking and entering text works fine,
but when I click "save", nothing happens.  in IE, that is.  if I look at the site in
Firefox, the note is there.

- if you click "edit this comment" on an existing note, and then click cancel,
the note disappears (in Firefox).  double-clicking on the associated block no
longer works, after that, so the note is still in there somewhere...

- many notes added to the same place may squeeze the original text into a
very narrow column.  note sure how to address that, but some kind of "mini-
mize" or "hide" feature could be nice.

</F>



_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] status of development documentation

Fred Drake-3
In reply to this post by Michael Foord
On Thursday 22 December 2005 05:19, Michael Foord wrote:
 > Hmmm... I submitted some plain text (might have been reST actually) docs
 > as a suggested addition to urllib2. The response from the maintainer)
 > was that I ought to submit it as patches against the original Tex
 > document.

Did you submit this as a documentation issue on the SF tracker?  If this is
still outstanding, please point me to the submission.

 > *However* - there was no implication that the maintainer was happy to
 > work with plain text submissions.

This sounds like a specific individual isn't interested in converting to
LaTeX, which isn't surprising (though unfortunate).  We'll have to find a
better way to handle this, since I don't want to be turning away plain text
contributions due to format.

I hope it wasn't me, in a moment of madness.  :-/


  -Fred

--
Fred L. Drake, Jr.   <fdrake at acm.org>
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] status of development documentation

Michael Foord
Fred L. Drake, Jr. wrote:
> On Thursday 22 December 2005 05:19, Michael Foord wrote:
>  > Hmmm... I submitted some plain text (might have been reST actually) docs
>  > as a suggested addition to urllib2. The response from the maintainer)
>  > was that I ought to submit it as patches against the original Tex
>  > document.
>
> Did you submit this as a documentation issue on the SF tracker?  If this is
> still outstanding, please point me to the submission.
>

I submitted it as a patch in the documentation category. (probably hence
the response which effectively says 'this isn't a patch').

https://sourceforge.net/tracker/?func=detail&atid=305470&aid=1216942&group_id=5470


>  > *However* - there was no implication that the maintainer was happy to
>  > work with plain text submissions.
>
> This sounds like a specific individual isn't interested in converting to
> LaTeX, which isn't surprising (though unfortunate).  We'll have to find a
> better way to handle this, since I don't want to be turning away plain text
> contributions due to format.
>
> I hope it wasn't me, in a moment of madness.  :-/
>

No - I would have responded privately. It was John J Lee - who does a
sterling job of maintaining the code he creates.

I'm happy to do more work on making the document suitable for inclusion.

All the best,

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml

>
>   -Fred
>

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: status of development documentation

Aahz
In reply to this post by Fredrik Lundh
On Wed, Dec 21, 2005, Fredrik Lundh wrote:

> Phillip J. Eby wrote:
>>
>> And where characters like '<' and '>' occur frequently as part of the text,
>> especially in showing Python interactions like this:
>>
>>      >>> print "hello world"
>>      hello world
>>
>> I can't imagine trying to author the above in an HTML/XML based format,
>
> it's spelled
>
> >>> print "hello world"
>     hello world
>
> in HTML.

What about XHTML?
--
Aahz ([hidden email])           <*>         http://www.pythoncraft.com/

"Don't listen to schmucks on USENET when making legal decisions.  Hire
yourself a competent schmuck."  --USENET schmuck (aka Robert Kern)
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: status of development documentation

Fredrik Lundh
Aahz wrote:

> >>      >>> print "hello world"
> >>      hello world
> >>
> >> I can't imagine trying to author the above in an HTML/XML based format,
> >
> > it's spelled
> >
> > >>> print "hello world"
> >     hello world
> >
> > in HTML.
>
> What about XHTML?

same thing.

not that I understand why anyone would author in XHTML, though.

</F>



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: status of development documentation

Torsten Bronger
Hallöchen!

"Fredrik Lundh" <[hidden email]> writes:

> [...]
>
> not that I understand why anyone would author in XHTML, though.

Because you can use XSLT on it.

Tschö,
Torsten.

--
Torsten Bronger, aquisgrana, europa vetus            ICQ 264-296-646

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: status of development documentation

Fredrik Lundh
Torsten Bronger wrote:

> > not that I understand why anyone would author in XHTML, though.
>
> Because you can use XSLT on it.

    tidy -asxml -n source | xsltengine

</F>



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: status of development documentation

Torsten Bronger
Hallöchen!

"Fredrik Lundh" <[hidden email]> writes:

> Torsten Bronger wrote:
>
>>> not that I understand why anyone would author in XHTML, though.
>>
>> Because you can use XSLT on it.
>
>     tidy -asxml -n source | xsltengine

I would have to add that to every processing line in my batch
scripts.  Just to avoid some slashes?  Anyway ... a minor question.

Tschö,
Torsten.

--
Torsten Bronger, aquisgrana, europa vetus            ICQ 264-296-646

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: status of development documentation

Fredrik Lundh
Torsten Bronger wrote:

> I would have to add that to every processing line in my batch
> scripts.  Just to avoid some slashes?

no, to avoid unnecessary syntax errors in your XSLT processor.  a
HTML parser is more tolerant than an XML parser, and tidy is more
tolerant than an ordinary HTML parser.

</F>



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig