[Twisted-Python] lore

[David Reid]

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

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
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (Darwin)

iD8DBQFEa55orsrO6aeULcgRAilhAJ9s8uA8XuIRrRO/3jMA3s9keUH9JwCgoySY
ZTcN7w4Rf2EoF2RKoPajVyI=
=LpZH
-----END PGP SIGNATURE-----