David Goodger
2017-06-23 02:39:01 UTC
On Thu, Jun 22, 2017 at 11:15 AM, Guenter Milde via Docutils-develop
If we are going to prune the doctree, the note should stay in
RELEASE_NOTES / Future changes to give clients a prominent advance
warning.
I am still in favour of doctree pruning: In horticulture, pruning is a
means to facilitate development and growth, adapt to changes and get a
balanced tree. The same applies to the Docutils doctree.
I don't see the need for any pruning. And stretching the horticultural
metaphor to software is really going too far.
While I understand your desire to tidy up and minimize, change for
change's sake is often counterproductive. There is an old engineering
saying: if it ain't broke, don't fix it. Making these changes would
require first issuing deprecation warnings, and would risk introducing
incompatibilities & bugs. It's just not worth the effort required.
I'd much rather see you employ your time improving Docutils (by fixing
bugs, adding features, documenting, etc.) instead of churning up the
code for no real benefit (but real risk).
And I'd much, *much* rather you didn't waste time with these perennial
arguments.
It ain't broke.
It should be as late in the process as possible.
docutils.transforms.writer_aux.Admonitions to transform the doctree,
so there are no redundant methods there.
The Manpage and ODF writers already have simple code that does the
job. They could easily be adapted to use the same transform to
simplify their code.
name="..." attributes="...">. Where do we draw the line? No, the DTD
is fine as it is.
hampering any such efforts.
-1 on any doctree pruning until I see strong evidence that making
these changes would be a significant net benefit.
David Goodger
<http://python.net/~goodger>
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-develop mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-develop
Please use "Reply All" to reply to the list.
Also removed the text about pruning the doctree; it's in
docs/dev/todo.txt.
A possible change in the doctree should be done before 1.0 comes out.docs/dev/todo.txt.
If we are going to prune the doctree, the note should stay in
RELEASE_NOTES / Future changes to give clients a prominent advance
warning.
I am still in favour of doctree pruning: In horticulture, pruning is a
means to facilitate development and growth, adapt to changes and get a
balanced tree. The same applies to the Docutils doctree.
metaphor to software is really going too far.
While I understand your desire to tidy up and minimize, change for
change's sake is often counterproductive. There is an old engineering
saying: if it ain't broke, don't fix it. Making these changes would
require first issuing deprecation warnings, and would risk introducing
incompatibilities & bugs. It's just not worth the effort required.
I'd much rather see you employ your time improving Docutils (by fixing
bugs, adding features, documenting, etc.) instead of churning up the
code for no real benefit (but real risk).
And I'd much, *much* rather you didn't waste time with these perennial
arguments.
It ain't broke.
* The "doctest" element can be replaced by literal blocks with a class
attribute (similar to the "code" directive output).
The syntax shall be left in reST.
[DG 2017-01-02:] +0.
I hereby revise my vote to -0.attribute (similar to the "code" directive output).
The syntax shall be left in reST.
[DG 2017-01-02:] +0.
* "Normalize" special admonitions (note, hint, warning, ...) during parsing
(similar to _`transforms.writer_aux.Admonitions`). There is no need to
keep them as distinct elements in the doctree specification.
[DG 2017-01-02:] -1: <note>{body}</> is much more concise and
expressive than <admonition><title>Note</>{body}</>, and the title
translation can be put off until much later in the process.
<admonition class=note>
<title>
Note
{body}
is more verbose. However, a document is rarely printed/used as doctree or
XML, other target formats do not have the 9 special "admonition
elements", so this difference is not very important.
Delaying the title translation as much as possible is very important.(similar to _`transforms.writer_aux.Admonitions`). There is no need to
keep them as distinct elements in the doctree specification.
[DG 2017-01-02:] -1: <note>{body}</> is much more concise and
expressive than <admonition><title>Note</>{body}</>, and the title
translation can be put off until much later in the process.
<admonition class=note>
<title>
Note
{body}
is more verbose. However, a document is rarely printed/used as doctree or
XML, other target formats do not have the 9 special "admonition
elements", so this difference is not very important.
It should be as late in the process as possible.
* allow us to remove 36 redundant methods (9 visit_*/depart_* method
pairs to handle the 9 subtypes of an admonition in the HTML, LaTeX,
Manpage, and ODF writers),
The HTML & LaTeX writers already usepairs to handle the 9 subtypes of an admonition in the HTML, LaTeX,
Manpage, and ODF writers),
docutils.transforms.writer_aux.Admonitions to transform the doctree,
so there are no redundant methods there.
The Manpage and ODF writers already have simple code that does the
job. They could easily be adapted to use the same transform to
simplify their code.
* reduce the complexity of the doctree.
Docutils' expressive doctree is a feature, not a bug.This simplifies the DTD and our documentation (there is no 1:1 rST
syntax element <-> doctree node mapping anyway).
Extrapolating, we could end up with a DTD that has one element: <tagsyntax element <-> doctree node mapping anyway).
name="..." attributes="...">. Where do we draw the line? No, the DTD
is fine as it is.
It also helps clients converting Docutils XML into other formats
Where's your evidence? I don't think the extent of the doctree ishampering any such efforts.
-1 on any doctree pruning until I see strong evidence that making
these changes would be a significant net benefit.
David Goodger
<http://python.net/~goodger>
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-develop mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-develop
Please use "Reply All" to reply to the list.