From: David P. <pr...@sf...> - 2004-06-25 23:28:55
|
There seems to be a lot of beefing about docutils lately. I'd hate to see this project fumble, because I really believe it stands to revolutionize technical document publishing. I'm wondering if we should halt the current development and do two things: * rationalize the reST markup to a very, very high degree. * refactor the code, with full documentation, stomping of bugs, and built-in flexibility for future development. I've no idea if this is would be a good thing. My suspicion is that the code is overly complex and inconsistent, and can be greatly simplified and made more accessible to new developers. I know that reST has a few flaws that could use fixing, especially as regards inconsistent markup conventions. Fow what it's worth, for *my* purposes, which includes several lengthy software and hardware user manuals, docutils is working very nicely; but I do find it challenging to understand the code, let alone modify it. -- David Priest -- 250 542-5208 WritersBlock Technical Communications |
From: David A. <da...@bo...> - 2004-06-26 01:00:16
|
"David Priest" <pr...@sf...> writes: > There seems to be a lot of beefing about docutils lately. I'd hate to > see this project fumble, because I really believe it stands to > revolutionize technical document publishing. > > I'm wondering if we should halt the current development and do two things: > * rationalize the reST markup to a very, very high degree. > * refactor the code, with full documentation, stomping of bugs, and > built-in flexibility for future development. > > I've no idea if this is would be a good thing. My suspicion is that > the code is overly complex and inconsistent, and can be greatly > simplified and made more accessible to new developers. I know that > reST has a few flaws that could use fixing, especially as regards > inconsistent markup conventions. > > Fow what it's worth, for *my* purposes, which includes several lengthy > software and hardware user manuals, docutils is working very nicely; > but I do find it challenging to understand the code, let alone modify > it. I think the refactoring part is a very worthwhile project and would happily contribute some cycles. Otherwise I fear the project collapsing of its own weight... but please take my inline markup patch first !! ;-) -- Dave Abrahams Boost Consulting http://www.boost-consulting.com |
From: David G. <go...@py...> - 2004-06-26 01:23:53
|
[David Priest] > There seems to be a lot of beefing about docutils lately. I'd hate > to see this project fumble, because I really believe it stands to > revolutionize technical document publishing. Don't worry, I have a thick skin. If I didn't, I would have given up back in the first draft spec days, before a single line of code was written. > I'm wondering if we should halt the current development and do two things: > * rationalize the reST markup to a very, very high degree. ... > I know that reST has a few flaws that could use fixing, especially > as regards inconsistent markup conventions. This idea pops up regularly. I suggest that "plaintext markup" is an exercise in compromise, and there is no such thing as perfection. Also, once a particular syntax has enough momentum behind it, it may be too expensive to change. If another debate springs up out of this, I think I'll sit it out. > * refactor the code, with full documentation, stomping of bugs, and > built-in flexibility for future development. Any effort toward that would be welcome. Everyone is welcome to take any chunk of code that needs work and go to it. > I've no idea if this is would be a good thing. My suspicion is that > the code is overly complex and inconsistent, and can be greatly > simplified and made more accessible to new developers. Undoubtedly there are lots of places that could use improvement. > Fow what it's worth, for *my* purposes, which includes several > lengthy software and hardware user manuals, docutils is working very > nicely; but I do find it challenging to understand the code, let > alone modify it. Could it be that parsers are just inherently complex? I don't know if that's true, but I hope so. [David Abrahams] > I think the refactoring part is a very worthwhile project and would > happily contribute some cycles. Otherwise I fear the project > collapsing of its own weight... You're a pessimist ;-) > but please take my inline markup patch first !! ;-) That's right, let's make the code *more* complicated first! ;-) -- David Goodger |
From: David A. <da...@bo...> - 2004-06-26 02:45:15
|
David Goodger <go...@py...> writes: > > Fow what it's worth, for *my* purposes, which includes several > > lengthy software and hardware user manuals, docutils is working very > > nicely; but I do find it challenging to understand the code, let > > alone modify it. > > Could it be that parsers are just inherently complex? I don't know if > that's true, but I hope so. Why not hope that they can be described simply and elegantly so we can make the ReST parser maintainable? > [David Abrahams] > > I think the refactoring part is a very worthwhile project and would > > happily contribute some cycles. Otherwise I fear the project > > collapsing of its own weight... > > You're a pessimist ;-) I don't think so. I've just messed up my own projects enough times to know when the complexity is getting unmanageable. > > but please take my inline markup patch first !! ;-) > > That's right, let's make the code *more* complicated first! ;-) Right ;-> -- Dave Abrahams Boost Consulting http://www.boost-consulting.com |
From: Beni C. <cb...@us...> - 2004-07-02 14:46:37
|
David Priest wrote: > I'm wondering if we should halt the current development and do two things: > * rationalize the reST markup to a very, very high degree. > I don't see how that can be done, except by considering flaws and possible improvements when somebody notices them. If you see specific inconsitencies, please post them. -- Beni Cherniavsky <cb...@us...> Note: I can only read email on week-ends... |