[Twisted-Python] lore

[Cory Dodt]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Well, I was a contributor to Lore in ages past and was one of the ones who
thought it was a great idea.  Now I'm in the other camp, and I actually have
been using reST for all kinds of documentation on my end.  It's just so much
more convenient to type.

I'm not opposed to saving my documents as HTML-like syntax, but I hate typing
angle brackets.  After trying out many different approaches, I have decided
that my primary requirement in a documentation system is that it be easy to
type in documentation.  That, and nothing else, keeps me updating my
documentation regularly.  That and nothing else would convince me to generate
more documentation where it's missing.

I might be dissuaded if I saw that there was excellent tool support for Lore
out there.  What tools do people use to write Lore documents? Nvu?  How do you
handle doing the special lore-specific markup like Python code snippets?

- From what I remember about Lore, it doesn't do anything reST can't do; more
than that, reST can be converted to Lore without a lot of work.  (Round-trip
should even be possible, if that was for some reason desirable.)  So the
bottom line is: It's all about editor preference.  I would happily use Nvu if
I knew that the output would be Lore without any extra fiddling.

C


David Reid wrote:
> James Y Knight wrote:
>>> JP/Exarkun is against ReST as an input format for the documentation
>>> system. Writing an input plugin for lore to recognize it isn't a good
>>> first step, getting agreement that writing such a plugin would be Good
>>> is a good first step. From http://twistedmatrix.com/trac/ticket/1515:
>>>> All documentation for all Twisted projects should use lore. There
>>>> should only be one source format for documentation: even though we
>>>> could write a ReST input driver, doing so would defeat a large portion
>>>> of the purpose of lore, which is to make it easy to write and maintain
>>>> documentation (requiring everyone to learn lore xhtml and ReST is
>>>> harder than requiring everyone to learn lore xhtml).
> 
> If I'm not lazy this input driver is going to get written to convert the
> existing web2 docs anyway.  I think he's mainly saying he's against it
> for the purposes of allowing multiple documentation formats in the
> source tree.  I don't think he'd find it terribly objectionable as a
> "feature" of lore.  Atleast not enough to finding the energy to prevent
> it from happening.
> 
>>> I disagree with that conclusion, but have given up arguing the point. If
>>> there are others who support my view, now would be a good time to speak
>>> up. You of course get extra bonus points if you've actually contributed
>>> to documentation in twisted.
> 
> I just don't see any clear benefit ReST has over lore.  Especially not
> with the amount of existing documentation that is in lore.  If anyone
> would like to point out the benefit I'll gladly listen.
> 
> -David
> 
> --
> "Usually the protocol is this: I appoint someone for a task,
> which they are not qualified to do.  Then, they have to fight
> a bear if they don't want to do it." -- Glyph Lefkowitz

_______________________________________________
Twisted-Python mailing list
Twisted-Python at twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFEbKgC3A5SrXAiHQcRAhl/AJ91K/mScJvHmonGM+Cbqpa4S+9gMQCfVKXM
wVwd3pIrSD7uTBFyuJntwIo=
=r7+i
-----END PGP SIGNATURE-----