Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[8583] trunk/docutils
|
From: <mi...@us...> - 2020-12-01 10:53:31
|
Revision: 8583
http://sourceforge.net/p/docutils/code/8583
Author: milde
Date: 2020-12-01 10:53:27 +0000 (Tue, 01 Dec 2020)
Log Message:
-----------
Documentation update.
Restructuring, New input, and fixed links for TODO list item
"Adaptable file extensions".
Update/fix some source comments.
Modified Paths:
--------------
trunk/docutils/docs/dev/todo.txt
trunk/docutils/docutils/frontend.py
trunk/docutils/docutils/nodes.py
trunk/docutils/docutils/parsers/rst/directives/images.py
Modified: trunk/docutils/docs/dev/todo.txt
===================================================================
--- trunk/docutils/docs/dev/todo.txt 2020-12-01 09:38:02 UTC (rev 8582)
+++ trunk/docutils/docs/dev/todo.txt 2020-12-01 10:53:27 UTC (rev 8583)
@@ -156,7 +156,7 @@
settings. These partially solve the problem, allowing or disabling
**all** file accesses, but not limited access.
-* Configuration file handling needs discussion:
+* Configuration_ file handling needs discussion:
- There should be some error checking on the contents of config
files. How much checking should be done? How loudly should
@@ -497,7 +497,7 @@
* Add support for _`plugins`.
* _`Config directories`: Currently, ~/.docutils, ./docutils.conf/, &
- /etc/docutils.conf are read as configuration files. Proposal: allow
+ /etc/docutils.conf are read as configuration_ files. Proposal: allow
~/.docutils to be a a configuration *directory*, along with
/etc/docutils/ and ./docutils.conf/. Within these directories,
check for config.txt files. We can also have subdirectories here,
@@ -900,94 +900,6 @@
contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG
2001-08-10.
-* .. _adaptable file extensions:
-
- In target URLs, it would be useful to not explicitly specify the
- file extension. If we're generating HTML, then ".html" is
- appropriate; if PDF, then ".pdf"; etc. How about using ".*" to
- indicate "choose the most appropriate filename extension"? For
- example::
-
- .. _Another Document: another.*
-
- What is to be done for output formats that don't *have* hyperlinks?
- For example, LaTeX targeted at print. Hyperlinks may be "called
- out", as footnotes with explicit URLs. (Don't convert the links.)
-
- But then there's also LaTeX targeted at PDFs, which *can* have
- links. Perhaps a runtime setting for "*" could explicitly provide
- the extension, defaulting to the output file's extension.
-
- Should the system check for existing files? No, not practical.
-
- Handle documents only, or objects (images, etc.) also?
-
- If this handles images also, how to differentiate between document
- and image links? Element context (within "image")? Which image
- extension to use for which document format? Again, a runtime
- setting would suffice.
-
- This may not be just a parser issue; it may need framework support.
-
- Mailing list threads: `Images in both HTML and LaTeX`__ (especially
- `this summary of Lea's objections`__), `more-universal links?`__,
- `Output-format-sensitive link targets?`__
-
- __ http://thread.gmane.org/gmane.text.docutils.user/1239
- __ http://article.gmane.org/gmane.text.docutils.user/1278
- __ http://thread.gmane.org/gmane.text.docutils.user/1915
- __ http://thread.gmane.org/gmane.text.docutils.user/2438
-
- Idea from Jim Fulton: an external lookup table of targets:
-
- I would like to specify the extension (e.g. .txt) [in the
- source, rather than ``filename.*``], but tell the converter to
- change references to the files anticipating that the files will
- be converted too.
-
- For example::
-
- .. _Another Document: another.txt
-
- rst2html.py --convert-links "another.txt bar.txt" foo.txt
-
- That is, name the files for which extensions should be converted.
-
- Note that I want to refer to original files in the original text
- (another.txt rather than another.txt) because I want the
- unconverted text to stand on its own.
-
- Note that in most cases, people will be able to use globs::
-
- rst2html.py --convert-link-extensions-for "`echo *.txt`" foo.txt
-
- It might be nice to be able to use multiple arguments, as in::
-
- rst2html.py --convert-link-extensions-for *.txt -- foo.txt
-
- ::
-
- > What is to be done for output formats
- > that don't have hyperlinks?
-
- Don't convert the links.
-
- ::
-
- > Handle documents only, or objects
- > (images, etc.) also?
-
- No, documents only, but there really is no need for gueswork.
- Just get the file names as command-line arguments. EIBTI
- [explicit is better than implicit].
-
- For images, we probably need separate solution (which is being
- worked on), whereas for documents, the issue is basically
- interlinking between reStructuredText documents. IMO, this cries
- for support for multiple input and output files, i.e. support for
- documents which comprise multiple files. Adding adaptable file
- extensions seems like a kludge. // FW
-
* Implement the header row separator modification to table.el. (Wrote
to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting
support for "=====" header rows. On 2001-08-17 he replied, saying
@@ -1239,7 +1151,157 @@
particular, see the bodies of definition lists.
+Adaptable file extensions
+-------------------------
+Questions
+`````````
+
+Should Docutils support adaptable file extensions in hyperlinks?
+
+ In the rST source, sister documents are ".txt" files. If we're
+ generating HTML, then ".html" is appropriate; if PDF, then ".pdf";
+ etc.
+
+Handle documents only, or objects (images, etc.) also?
+
+ Different output formats support different sets of image formats (HTML
+ supports ".svg" but not ".pdf", pdfLaTeX supports ".pdf" but not ".svg",
+ LaTeX supports only ".eps").
+
+ This is less urgent 2020 than previously, as `pdflatex` and
+ `lualatex` are now standard and support most image formats. Also, a
+ wrapper like `rubber`__ that provide on-the-fly image conversion
+ depend on the "wrong" extension in the LaTeX source.
+
+ __ https://pypi.org/project/rubber/
+
+At what point should the extensions be substituted?
+
+ Transformations:
+ Fits well in the Docutils processing framework. (Writer-specific
+ configuration is still possible in the respective sections of the
+ configuration_ file.)
+
+ Writers:
+ May be simpler to code.
+
+ Pre- or post-processing:
+ Can be implemented independent of Docutils -- keeps Docutils simple.
+
+ ... those who need more sophisticated filename extension
+ tweaking can simply use regular expressions, which isn't too
+ difficult due to the determinability of the writers. So there
+ is no need to add a complex filename-extension-handling feature
+ to Docutils.
+
+ --- `Lea Wiemann in docutils-users 2004-06-04`__
+
+ __ https://sourceforge.net/p/docutils/mailman/message/6918089/
+
+
+Proposals
+`````````
+
+How about using ".*" to indicate "choose the most appropriate filename
+extension"? For example::
+
+ .. _Another Document: another.*
+
+* My point about using ``.*`` is that any other mechanism inside reST
+ leads to too many ambiguities in reading reST documents; at least
+ with ``.*`` it's clear that some kind of substitution is going on.
+
+ --- Aahz
+
+* What is to be done for output formats that don't *have* hyperlinks?
+ For example, LaTeX targeted at print. Hyperlinks may be "called
+ out", as footnotes with explicit URLs. (Don't convert the links.)
+
+ But then there's also LaTeX targeted at PDFs, which *can* have
+ links. Perhaps a runtime setting for "*" could explicitly provide
+ the extension, defaulting to the output file's extension.
+
+* If this handles images also, how to differentiate between document
+ and image links? Element context (within "image")? Which image
+ extension to use for which document format? For HTML output, there
+ is no reliable way of determining which extension to use (svg, png,
+ jpg, jpeg, gif, ...).
+
+ Should the system check for existing files? No, not practical (the
+ image files may be not available when the document is processed to HTML).
+
+ Mailing list threads: `Images in both HTML and LaTeX`__ (especially
+ `this summary of Lea's objections`__).
+
+ __ https://sourceforge.net/p/docutils/mailman/docutils-users/thread/40BAA4B7.5020801%40python.org/#msg6918066
+ __ https://sourceforge.net/p/docutils/mailman/message/6918089/
+
+Chris Liechti suggests a new ``:link:`` role in `more-universal
+links?`__::
+
+ .. role:: link(rewrite)
+ :transform: .txt|.html
+
+ and then to use it::
+
+ for more information see :link:`README.txt`
+
+ it would be useful if it supported an additional option
+ ``:format: html`` so that separate rules for each format can be
+ defined. (like the "raw" role)
+
+__ https://sourceforge.net/p/docutils/mailman/message/6919484/
+
+
+Idea from Jim Fulton: an external lookup table of targets:
+
+ I would like to specify the extension (e.g. .txt) [in the
+ source, rather than ``filename.*``], but tell the converter to
+ change references to the files anticipating that the files will
+ be converted too.
+
+ For example::
+
+ .. _Another Document: another.txt
+
+ rst2html.py --convert-links "another.txt bar.txt" foo.txt
+
+ That is, name the files for which extensions should be converted.
+
+ Note that I want to refer to original files in the original text
+ (another.txt rather than another.txt) because I want the
+ unconverted text to stand on its own.
+
+ Note that in most cases, people will be able to use globs::
+
+ rst2html.py --convert-link-extensions-for "`echo *.txt`" foo.txt
+
+ It might be nice to be able to use multiple arguments, as in::
+
+ rst2html.py --convert-link-extensions-for *.txt -- foo.txt
+
+ | > Handle documents only, or objects
+ | > (images, etc.) also?
+
+ No, documents only, but there really is no need for guesswork.
+ Just get the file names as command-line arguments. EIBTI
+ [explicit is better than implicit].
+
+In `Patch #169`__ `Hyperlink extension rewriting`, John L. Clark
+suggests command line options that map to-be-changed file extensions, e.g.::
+
+ rst2html --map-extension rst html --map-extension jpg png \
+ input-filename.rst
+
+__ https://sourceforge.net/p/docutils/patches/169/
+
+ Specifying the mapping as regular expressions would make this
+ approach more generic and easier to implement (use ``re.replace``
+ and refer to the "re" module's documentation instead of coding and
+ documenting a home-grown extraction and mapping procedure).
+
+
Math Markup
-----------
@@ -1719,8 +1781,8 @@
This could be an interface to the Filter transform
(docutils.transforms.components.Filter).
- The ideas in `adaptable file extensions`_ above may also be
- applicable here.
+ The ideas in the `adaptable file extensions`_ section above may
+ also be applicable here.
SVG's "switch" statement may provide inspiration.
@@ -2611,8 +2673,8 @@
* support more graphic formats (especially SVG, the only standard
vector format for HTML)
-
+
Missing features
----------------
@@ -2627,9 +2689,9 @@
See https://tex.stackexchange.com/questions/26529/how-can-i-generate-pdf-metadata-from-latex#26530
https://tex.stackexchange.com/questions/161094/adding-custom-metadata-values-to-a-pdf-file
-
-
+
+
* Multiple author entries in docinfo (same thing as in html).
* Consider supporting the "compact" option and class argument (from
@@ -2812,6 +2874,16 @@
* Create a single dynamic_ or unqualified_ front end that can be
installed?
+ The "new" `argparse` module supports `partial parsing`_, so a
+ generic front end may parse and remove additional options to select
+ the reader/parser/writer and leave the remaining arguments intact
+ for ``publish_cmdline()``.
+
+.. _partial parsing:
+ https://docs.python.org/3/library/argparse.html#partial-parsing
+
+.. _configuration: ../user/config.html
+
..
Local Variables:
Modified: trunk/docutils/docutils/frontend.py
===================================================================
--- trunk/docutils/docutils/frontend.py 2020-12-01 09:38:02 UTC (rev 8582)
+++ trunk/docutils/docutils/frontend.py 2020-12-01 10:53:27 UTC (rev 8583)
@@ -20,8 +20,8 @@
`validate_encoding_error_handler`,
`validate_encoding_and_error_handler`,
`validate_boolean`, `validate_ternary`, `validate_threshold`,
- `validate_colon_separated_string_list`,
- `validate_comma_separated_string_list`,
+ `validate_colon_separated_list`,
+ `validate_comma_separated_list`,
`validate_dependency_file`.
* `make_paths_absolute`.
* SettingSpec manipulation: `filter_settings_spec`.
@@ -175,8 +175,8 @@
config_parser=None, config_section=None):
"""Check/normalize list arguments (split at "," and strip whitespace).
"""
- # `value` is already a ``list`` when given as command line option
- # and "action" is "append" and ``unicode`` or ``str`` else.
+ # `value` may be ``unicode``, ``str``, or a ``list`` (when given as
+ # command line option and "action" is "append").
if not isinstance(value, list):
value = [value]
# this function is called for every option added to `value`
Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py 2020-12-01 09:38:02 UTC (rev 8582)
+++ trunk/docutils/docutils/nodes.py 2020-12-01 10:53:27 UTC (rev 8583)
@@ -1964,7 +1964,7 @@
for `docutils.writers.Writer` subclasses). Unimplemented methods will
raise exceptions.
- For sparse traversals, where only certain node types are of interest,
+ For sparse traversals, where only certain node types are of interest, use
subclass `SparseNodeVisitor` instead. When (mostly or entirely) uniform
processing is desired, subclass `GenericNodeVisitor`.
Modified: trunk/docutils/docutils/parsers/rst/directives/images.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/images.py 2020-12-01 09:38:02 UTC (rev 8582)
+++ trunk/docutils/docutils/parsers/rst/directives/images.py 2020-12-01 10:53:27 UTC (rev 8583)
@@ -53,9 +53,9 @@
'width': directives.length_or_percentage_or_unitless,
'scale': directives.percentage,
'align': align,
- 'name': directives.unchanged,
'target': directives.unchanged_required,
- 'class': directives.class_option}
+ 'class': directives.class_option,
+ 'name': directives.unchanged}
def run(self):
if 'align' in self.options:
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
