Activity for Docutils: Documentation Utilities
-
Günter Milde modified ticket #61
Add usemap option to image directive
-
As an "image map" is only supported by HTML output and a rarely used feature, the cost of increased complexity and documentation needs exceeds the benefits for Docutils. Possible workarounds are raw HTML and embedded SVG images (cf. the solved [feature-requests:#100]).
-
patch to make figure and table captions hyperlink targets
-
See also [feature-requests:#60] for allowing multi-term definitions in the doctree and writer support. It is solved by commit [r9747] which changes the DTD, documentation, and nodes.definition_list_item.content_model to allow multiple terms for one definition.
-
The syntax implemented in the proposed patch has one drawback explained by David Goodger in the original docutils-users thread: Perhaps we could define definition list items as one term per line, so this input: term 1 term 2 definition would produce this output: <definition_list> <definition_list_item> <term> term 1 <term> term 2 <definition> <paragraph> definition The current output is: <paragraph> term 1 term 2 <system_message level="3" line="3" source="<stdin>" type="ERROR"> <paragraph> Unexpected...
-
A possible syntax for reStructuredText input of multi-term definition lists is proposed in [patches:#95].
-
Fixed by applying [patches:#47].
-
Attributes in the main document are overriden
-
Fixed by appliying [patches:47].
-
Add :figname: option to the figure directive
-
The rST syntax for internal hyperlink targets applies a "name/label" to the following element. It can be used to name a figure element: .. _figure-label: .. figure:: myfile.png :name: imagelabel Figure caption. creates the HTML snippet: <figure id="figure-label"> <img alt="myfile.png" id="imagelabel" src="myfile.png" /> <figcaption> <p>Figure caption.</p> </figcaption> </figure> A "figname" directive option would provide an alternative way to name a figure element: -1 There should be one-- and preferably...
-
@aa-turner: Do the tests still fail on Windows?
-
Refactor HTML4 writer tests.
-
HTML4 writer: catch/report errors when reading image file.
-
Use writer instances instead of names in test scripts.
-
Refactor HTML5 writer tests.
-
HTML writer: Fix part "html_head" if "output_encoding" setting is 'unicode'.
-
Revert test template file extension from "rst" to "txt".
-
Review "docutils.utils" after type hint addition.
-
@aa-turner: Could you create a patch that just Changes the default root_prefix to '' (the empty string), and only applies the root_prefix behaviour when it is non-empty (i.e. a user has configured the setting) I agree that this is easier to explain (while the current implementation does not need a conditional). As the change is also backwards-compatible we can implement it without advance warning.
-
status: open --> open-fixed Fixed in [r9657], so the 0.22 sdist will come with tox.ini Thank you for the report.
-
status: open --> open-fixed Fixed in [r9657]. Thank you for the report.
-
Refactor "Include" directive class.
-
engelbert gruber committed [r9908] on Code
Fix file corruption on rename to rst
-
Aside from verbosity, I'm unsure of the argument to change this. Readabilty counts. Verbosity can be managed with a type alias, This was my first idea. The best name for such a type alias would be "Node" (for any node in a document tree). The name was already take by a class documented as "Abstract base class of nodes in a document tree." So, instead [r9901] makes sure that all methods and attributes that are common to "Element" and "Text" are also defined for "Node": Node.children is now an empty...
-
rename README.txt to rst
-
Adam Turner modified a comment on ticket #187
nut i would only apply on svn ... might be not what's wanted
-
i could apply the rename this week ... nag me
-
infrastructure docutils-update.local should prefer .rst but falls back on .txt ./docs/user/Makefile.docutils-update has fixed filenames but is only one file
-
sandbox/infrastructure/docutils-update.local errors will pop up when run , no problem to me
-
rename txt to rst
-
Typing and `docutils.nodes.Node`
-
Typing and `docutils.nodes.Node`
-
Rename .txt files to .rst
-
applied the patch
-
Small code updates to "modern" syntax constructs.
-
Add type hints to ``docutils.parsers.rst.directives``.
-
Fix type hints (typing.TypeAlias is new in Python 3.12).
-
Fix CSS for HTML5: right align code line numbers.
-
Use base class "Node" instead of `Element | Node` in type hints.
-
Fixes and cleanup
-
log tryout of sdist install from testpypi
-
use = as section title underlining
-
change command line option --use-macro-references to the pair
-
remove stale parts
-
add description
-
infrastructure docutils-update.local should prefer .rst but falls back on .txt ./docs/user/Makefile.docutils-update has fixed filenames but is only one file On Sun, 11 Aug 2024 at 13:57, engelbert gruber grubert@users.sourceforge.net wrote: sandbox/infrastructure/docutils-update.local errors will pop up when run , no problem to me On Fri, 9 Aug 2024 at 11:35, Günter Milde milde@users.sourceforge.net wrote: We would need to adapt background scripts, too. I am unsure whether the following changes correctly...
-
i could apply the rename this week ... nag me On Tue, 13 Aug 2024 at 12:42, engelbert gruber grubert@users.sourceforge.net wrote: infrastructure docutils-update.local should prefer .rst but falls back on .txt ./docs/user/Makefile.docutils-update has fixed filenames but is only one file On Sun, 11 Aug 2024 at 13:57, engelbert gruber grubert@users.sourceforge.net wrote: sandbox/infrastructure/docutils-update.local errors will pop up when run , no problem to me On Fri, 9 Aug 2024 at 11:35, Günter Milde...
-
move release.sh into attic
-
remove antique
-
remove unused file
-
nut i would only apply on svn ... might be not what's wanted On Tue, 13 Aug 2024 at 12:43, engelbert gruber grubert@users.sourceforge.net wrote: i could apply the rename this week ... nag me On Tue, 13 Aug 2024 at 12:42, engelbert gruber grubert@users.sourceforge.net wrote: infrastructure docutils-update.local should prefer .rst but falls back on .txt ./docs/user/Makefile.docutils-update has fixed filenames but is only one file On Sun, 11 Aug 2024 at 13:57, engelbert gruber grubert@users.sourceforge.net...
-
FIX do not generate .rst.html files
-
FIX mostly man is used
-
rename README and TODO to rst
-
move htmlfile.lst to in use section
-
add URI-reference
-
add support and preference for rst-files
-
rename to .rst
-
move unused scripts in used section
-
Clarify documentation of the "URI reference" data type in elements and directives.
-
The second commit in the patch goes further, by rejecting absolute paths when used in relative references. This is optional, but as I argue above I think allowing absolute paths in relative references leads to surprising behaviour the resolution is easy if you want to keep using absolute paths (just use file:///). Using the "file" scheme does not work if you want to generate HTML and LaTeX/PDF output from the same source with the HTML to be served via https and linking to images. The rejection of...
-
The second commit in the patch goes further, by rejecting absolute paths when used in relative references. This is optional, but as I argue above I think allowing absolute paths in relative references leads to surprising behaviour the resolution is easy if you want to keep using absolute paths (just use file:///). Using file does not work if you want to generate HTML that should be served via https and * create two output versions with/without embedding images from the same source, or * read the...
-
I am in favour of using unquote(). Now it seems that (at least from wikipedia) this scheme of using | is not standardised/used, and might just be a Python quirk The "|" seems to be not Python specific, however, it is obsolete. Wiki says: On Microsoft Windows systems, the normal colon (:) after a device letter has sometimes been replaced by a vertical bar (|) in file URLs. This reflected the original URL syntax, which made the colon a reserved character in a path part. Since Internet Explorer 4, file...
-
I think we have two options. (1) support absolute paths on every platform, document as such. (2) make absolute paths return an error on Linux. (3) support URI-references: full URI | relative reference (relative to a "base URI"), e.g.be an "absolute path reference" (starting with one slash) or a "relative path reference" (not starting with a slash). The first restores backwards compatibility, the second is needlessly restrictive and hard to explain. The third is consistent with what we document. The...
-
The parsing is correct: The image argument is a "URI reference": A URI-reference is either a URI or a relative reference. If the URI-reference's prefix does not match the syntax of a scheme followed by its colon separator, then the URI-reference is a relative reference. (RFC 3986) Hence, the example ~~~ .. image:: S:/Development/data/circle-broken.svg ~~~ describes an image accessible under scheme "S". Our problem is, that we cannot easily use relative paths (to keep flexibility regarding where to...
-
I think we have two options. (1) support absolute paths on every platform, document as such. (2) make absolute paths return an error on Linux. (3) support URI-references: URI | absolute (POSIX) path | relative (POSIX) path The first restores backwards compatibility, the second is needlessly restrictive and hard to explain. The third is consistent with what we document. It is also in line with "root-prefix" only being used if a path starts with "/". The different handling of Windows system paths is...
-
The parsing is correct: The image argument is a "URI reference": A URI-reference is either a URI or a relative reference. If the URI-reference's prefix does not match the syntax of a scheme followed by its colon separator, then the URI-reference is a relative reference. (RFC 3986) Hence, the example ~~~ .. image:: S:/Development/data/circle-broken.svg ~~~ describes an image accessible under scheme "S". Our problem is, that we cannot easily use relative paths (to keep flexibility regarding where to...
-
sandbox/infrastructure/docutils-update.local errors will pop up when run , no problem to me On Fri, 9 Aug 2024 at 11:35, Günter Milde milde@users.sourceforge.net wrote: We would need to adapt background scripts, too. I am unsure whether the following changes correctly describe the behaviour after applying this patch : --- a/sandbox/infrastructure/docutils-update.local+++ b/sandbox/infrastructure/docutils-update.local@@ -14,10 +14,10 @@ # # ATTENTION #-# Any .html document with a corresponding .txt...
-
I think we should use Path.as_uri() instead of .as_posix(). Done in [r9882].
-
Fixup [r9880]. Use `to_uri()` to get image URI in test sample.
-
Your analysis with "the uri_parts.scheme not in ('', 'file') check" beeing "the root cause" of the test failure is correct. This check was introduced in [r9501] "Refactor "_html_base" writer." However, even before (since introduction of image embedding in 0.18), the drive part was split from the path. To verify this, try PS> echo ".. image:: S:/Development/docutils/docutils/test/data/circle.svg" | python rst2html5.py --link-stylesheet --image-loading embed from a directory in a different drive. BTW:...
-
the second is needlessly restrictive and hard to explain. Suppose a user has a directive .. image:: /media/circle.svg. By default this will load the file under /media/circle.svg, as the user might expect if they think they are using filesystem paths, and don't realise the nuances of URI references. At some later date, this user sets root_prefix to /home/user/project/. The image directive will stop working, as it now looks for a file under /home/user/project/media/circle.svg. I think this behaviour...
-
I think we have two options. (1) support absolute paths on every platform, document as such. (2) make absolute paths return an error on Linux. (3) support URI-references: URI | absolute (POSIX) path | relative (POSIX) path The first restores backwards compatibility, the second is needlessly restrictive and hard to explain. The third is consistent with what we document. It is also in line with "root-prefix" only being used if a path starts with "/". The different handling of Windows system paths is...
-
I think we have two options. (1) support absolute paths on every platform, document as such. (2) make absolute paths return an error on Linux. (3) support URI-references: URI | absolute (POSIX) path | relative (POSIX) path The first restores backwards compatibility, the second is needlessly restrictive and hard to explain. The third is consistent with what we document. It is also in line with "root-prefix" only being used if a path starts with "/". The different handling of Windows system paths is...
-
Smaller fixups (formatting, comments)
-
We could say: If you want the telephone number to become a hyperlink, you can use a valid "tel:" URI (like tel:+35/12345.6789-33). If the link text should be different from the "href" value, use a "hyperlinke reference", either regular, anonymous or embedded. Example:: :contact: `1234`__ :address: at home ... __ tel:+33/456-1234 Would this suffice?
-
I would not want an "explicit mode" different from what is already implemented: The rST support for "standalone hyperlinks" is specified in http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#standalone-hyperlinks Although not listed explicitely, "tel:" is among the "known schemes, per the Official IANA Registry of URI Schemes" and indeed, the example tel:+45/123-4567 is converted to the XML <reference refuri="tel:+45/123-4567">tel:+45/123-4567</reference>. If a different URI and display...
-
The parsing is correct: The image argument is a "URI reference" ... The issue here now becomes why the tests were not failing on Linux, I believe. Both Windows and Linux would have had an absolute path (e.g. .. image:: /home/user/development/docutils/docutils/test/data/circle-broken.svg). On Windows, this failed due to misinterpreting the drive letter as a scheme. However, because the default root_prefix is /, when an absolute path is used on Unix, the scheme is '', imagepath.startswith('/') is True,...
-
The parsing is correct: The image argument is a "URI reference": A URI-reference is either a URI or a relative reference. If the URI-reference's prefix does not match the syntax of a scheme followed by its colon separator, then the URI-reference is a relative reference. (RFC 3986) Hence, the example ~~~ .. image:: S:/Development/data/circle-broken.svg ~~~ describes an image accessible under scheme "S". Our problem is, that we cannot easily use relative paths (to keep flexibility regarding where to...
-
Next try to fix Windows test failure because of image URI -> path conversion.
-
We would need to adapt background scripts, too. I am unsure whether the following changes correctly describe the behaviour after applying this patch : --- a/sandbox/infrastructure/docutils-update.local +++ b/sandbox/infrastructure/docutils-update.local @@ -14,10 +14,10 @@ # # ATTENTION # -# Any .html document with a corresponding .txt file is regenerated -# if the .txt has changed, but no new .html files will be generated. +# Any .html document with a corresponding .rst file is regenerated +# if...
-
Improve diff on test failure for ``test_html*_parts``
-
Fixups for nodes.py.
-
The parsing is correct: The image argument is a "URI reference": A URI-reference is either a URI or a relative reference. If the URI-reference's prefix does not match the syntax of a scheme followed by its colon separator, then the URI-reference is a relative reference. (RFC 3986) Hence, the example ~~~ .. image:: S:/Development/data/circle-broken.svg ~~~ describes an image accessible under scheme "S". Our problem is, that we cannot easily use relative paths (to keep flexibility regarding where to...
-
Move unused ``version_identifier()`` to a test helper
-
Add type hints to ``docutils.utils``
-
Add type hints to ``docutils.utils.urischemes``
-
Add type hints to ``docutils.writers``
-
Add type hints to ``docutils.parsers``
-
Add type hints to ``docutils.readers``
-
I have recreated the branch/patch for the rename, please have a look: https://github.com/AA-Turner/docutils/pull/17 https://github.com/AA-Turner/docutils/pull/17.patch All .txt files in docutils/, web/, and sandbox/infrastructure/ have been renamed. Writer template files remain unchanged. A
-
Fix Ruff
-
Fix Ruff
-
Fix comprehension syntax
-
Sorry, another failure. The root cause of this one seems to be the uri_parts.scheme not in ('', 'file') check. On Windows, we get the following, because drives in absolute paths are parsed as URI schemes: >>> uri 'S:/Development/docutils/docutils/test/data/circle-broken.svg' >>> urllib.parse.urlparse(uri).scheme 's' We could do something like Path(uri).is_file(), but that has the problems with using pathlib that you mentioned earlier... Full failure below, also on https://github.com/AA-Turner/docutils/actions/runs/10308701375/job/28536730749...
-
Test failure on Windows with embedded images
-
As another update, I have recently made several improvements to the draft conversion files (see [r9856] and [r9868]) that I've been working on over the last couple of weeks. I also have written to Günter (@milde) privately to resolve some other matters, relating to migrating issues and the authors map. A