SF.net SVN: docutils:[10120] trunk/docutils
milde--- via Docutils-checkins <[email protected]> Mon, 05 May 2025 13:51:58 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 10120
http://sourceforge.net/p/docutils/code/10120
Author: milde
Date: 2025-05-05 13:51:57 +0000 (Mon, 05 May 2025)
Log Message:
-----------
Documentation and formatting fixes (includes renaming of a config setting).
Rename settings variable "macro_references" to the match the (future)
non-standard behaviour "text_references". Command line options remain as-is.
Announce change of "text_references" to False in Docutils 1.0.
Add `writers.manpage.Writer.config_section_dependencies` so that
entries in section [manpage writer] override entries in section [writer].
Fix flake8 issues in manpage.py
Adapt tests.
Fix links and typos. Small edits for easier reading.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docutils/writers/manpage.py
trunk/docutils/test/test_writers/test_manpage.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2025-05-01 10:01:14 UTC (rev 10119)
+++ trunk/docutils/HISTORY.rst 2025-05-05 13:51:57 UTC (rev 10120)
@@ -48,7 +48,7 @@
- Drop short options ``-i`` and ``-o`` for ``--input-encoding``
and ``--output-encoding``.
- Change the default input encoding from ``None`` (auto-detect) to "utf-8".
- - Change the default value of the _root_prefix setting to the empty string
+ - Change the default value of the root_prefix_ setting to the empty string
(no change to the behaviour).
* docutils/io.py
@@ -86,7 +86,7 @@
* docutils/parsers/rst/languages/
- - Removed mistranslations of the "admonition" directive name.
+ - Remove mistranslations of the "admonition" directive name.
* docutils/parsers/rst/directives/__init__.py
@@ -156,7 +156,7 @@
* docutils/utils/_roman_numerals.py
- New implementation or Roman numeral support.
- Replaces the local copy of docutils/utils/roman.py.
+ Replaces the local copy of the roman.py package.
* docutils/utils/error_reporting.py
@@ -220,10 +220,11 @@
- Remove code for unused emdash bullets.
- Print Docutils version in header comment (feature-request #105).
- Stop converting text to full capitals (bug #481).
- - Add module function insert_URI_breakpoints.
- - Add command line option ``--macro-references``/``--text-references``
- to enable/disable usage of *man* macros .UR/.UE.
- - Proper reference output.
+ - Fix reference output (bug #497).
+ - Use macros .UR/.UE for hyperlink references unless the new
+ configuration setting text_references_ is True.
+ The current default is True (text references), it will change
+ to False (macro references) in Docutils 1.0.
* docutils/writers/null.py
@@ -4669,6 +4670,7 @@
.. _stylesheet_path: docs/user/config.html#stylesheet-path
.. _syntax_highlight: docs/user/config.html#syntax-highlight
.. _table_style: docs/user/config.html#table-style
+.. _text_references: docs/user/config.html#text_references
.. _theme: docs/user/config.html#theme
.. _theme_url: docs/user/config.html#theme-url
.. _toc_backlinks: docs/user/config.html#toc-backlinks
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2025-05-01 10:01:14 UTC (rev 10119)
+++ trunk/docutils/RELEASE-NOTES.rst 2025-05-05 13:51:57 UTC (rev 10120)
@@ -115,6 +115,10 @@
__ docs/user/latex.html#length-units
+* "manpage" writer:
+
+ - Change default of the text_references_ setting to False in Docutils 1.0.
+
* "odt" writer:
- Align adjustment of relative image paths with the behaviour of HTML
@@ -247,6 +251,9 @@
- Rename configuration setting "output" to "output_path_".
+ - The manpage writer now recognizes the sections [writers] and
+ [manpage writer] with the new setting `text_references`_.
+
Output changes
LaTeX:
Don't wrap references with custom reference-label_ in a ``\hyperref``
@@ -266,6 +273,7 @@
manpage:
Don't UPPERCASE section headings.
+ Handle hyperlink references (see text_references_).
null:
The "null" writer output changed from None to the empty string.
@@ -1444,6 +1452,7 @@
.. _input_encoding: docs/user/config.html#input-encoding
.. _[latex writers]: docs/user/config.html#latex-writers
.. _legacy_column_widths: docs/user/config.html#legacy-column-widths
+.. _text_references: docs/user/config.html#text-references
.. _math_output: docs/user/config.html#math-output
.. _old-format configuration files:
docs/user/config.html#old-format-configuration-files
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2025-05-01 10:01:14 UTC (rev 10119)
+++ trunk/docutils/docs/user/config.rst 2025-05-05 13:51:57 UTC (rev 10120)
@@ -2098,29 +2098,32 @@
[manpage writer]
----------------
-The `manpage writer`_ generates documents in the "roff" format
-for processing into UNIX `manual pages`_ with mandoc_ or groff_.
+The `manpage writer`_ generates documents in the roff_ markup language
+for processing into UNIX `manual pages`_ with, e.g., mandoc_ or groff_.
.. _manpage Writer: manpage.html
+.. _roff: https://en.wikipedia.org/wiki/Roff_(software)
.. _manual pages: https://en.wikipedia.org/wiki/Man_page
.. _mandoc: http://mandoc.bsd.lv/
.. _groff: https://gnu.org/software/groff/
-macro-references
+text_references
~~~~~~~~~~~~~~~~
-Output man-macros ``.UR``/``.UE`` for uri references
-and ``.MT``/``.ME`` for email-addresses.
-If False rendering of references is done by the manpage writer.
+Use a text rendering instead of the macros ``UR`` and ``MT`` for
+reference targets (URI references and email addresses).
+Some systems (e.g. Solaris troff) do not support these macros.
+Text references also prevent problems when groff_ is used on a
+terminal emulator that does not `support OSC8 sequences`__
+(alternatively, call groff_ with the option `-rU0`__).
-The option exists because 2024 or so, the man macros began to support
-OSC8 terminals, that became more available. But not everyone, every
-system supports OSC8, e.g. mandoc_ macros do not output OSC8.
+:Default: True (will change to False in Docutils 1.0).
+:Options: ``--macro-references``, ``--text-references``.
-:Default: False. ... will be True ... soon.
-:Options: ``--macro-references`` to set True, ``--text-references`` to set
- False.
+__ https://github.com/Alhadis/OSC8-Adoption/
+__ https://www.man7.org/linux/man-pages/man7/groff_man.7.html#Options
+
.. _ODF/ODT Writer:
[odf_odt writer]
Modified: trunk/docutils/docutils/writers/manpage.py
===================================================================
--- trunk/docutils/docutils/writers/manpage.py 2025-05-01 10:01:14 UTC (rev 10119)
+++ trunk/docutils/docutils/writers/manpage.py 2025-05-05 13:51:57 UTC (rev 10120)
@@ -17,7 +17,7 @@
7 miscellaneous
8 system administration
-Man pages are written *troff*, a text file formatting system.
+Man pages are written in the *roff* markup language.
See https://www.tldp.org/HOWTO/Man-Page for a start.
@@ -104,7 +104,8 @@
def insert_URI_breakpoints(s):
# TODO only for long URIs ?
- return NONBREAKING_INSERT_RE2.sub(r'\1' + NONPRINTING_BREAKPOINT,
+ return NONBREAKING_INSERT_RE2.sub(
+ r'\1' + NONPRINTING_BREAKPOINT,
NONBREAKING_INSERT_RE.sub(r'\1' + NONPRINTING_BREAKPOINT, s))
@@ -117,20 +118,23 @@
"""Formats this writer supports."""
settings_spec = (
- 'Manpage-Specific Options',
+ 'Manpage Writer Options',
None,
- (('Use man macros .UR/.UE and .MT/.ME for references ',
+ (('Write references in plain text form. (default)',
+ ['--text-references'],
+ {'action': 'store_true',
+ 'default': True, # remove in Docutils 1.0
+ 'validator': frontend.validate_boolean}),
+ ('Use man macros UR and MT for references.',
['--macro-references'],
- {'default': False, 'action': 'store_true',
- 'validator': frontend.validate_boolean}),
- ('Put references in plain text form.',
- ['--text-references'],
- {'dest': 'macro_references',
+ {'dest': 'text_references',
'action': 'store_false',
'validator': frontend.validate_boolean}),
),
)
+ config_section_dependencies = ('writers',)
+
output = None
"""Final translated form of `document`."""
@@ -219,12 +223,12 @@
def __init__(self, document) -> None:
nodes.NodeVisitor.__init__(self, document)
self.settings = settings = document.settings
- if settings.macro_references:
+ if settings.text_references:
+ self.visit_reference = self._visit_reference_no_macro
+ self.depart_reference = self._depart_reference_no_macro
+ else:
self.visit_reference = self._visit_reference_with_macro
self.depart_reference = self._depart_reference_with_macro
- else:
- self.visit_reference = self._visit_reference_no_macro
- self.depart_reference = self._depart_reference_no_macro
lcode = settings.language_code
self.language = languages.get_language(lcode, document.reporter)
self.head = []
@@ -238,8 +242,7 @@
self.compact_simple = None
# the list style "*" bullet or "#" numbered
self._list_char = []
- # writing the header .TH and .SH Name is postboned after
- # docinfo.
+ # writing the header .TH and .SH Name is postponed after docinfo.
self._docinfo = {
"title": "",
"subtitle": "",
@@ -352,13 +355,13 @@
):
self.body[i] = '.\n'
elif self.body[i][:4] in ('.UE\n', '.ME\n'):
- # if next item starts with
+ # if next item starts with
# a) a line end, disable it
if self.body[i+1][0] in ('\n', '\r'):
self.body[i+1] = '.' + self.body[i+1]
# b) with a separator: move the 1st char to current item
else:
- self.body[i] = "%s \\c\n" % ( self.body[i][:3])
+ self.body[i] = "%s \\c\n" % (self.body[i][:3])
return ''.join(self.head + self.body + self.foot)
def deunicode(self, text):
@@ -1108,16 +1111,17 @@
def _depart_reference_no_macro(self, node) -> None:
if 'refuri' in node:
- self.body.append(r" \%%<%s>" % insert_URI_breakpoints(node['refuri']))
+ self.body.append(r" \%%<%s>"
+ % insert_URI_breakpoints(node['refuri']))
# elif 'refid' in node:
def _visit_reference_with_macro(self, node) -> None:
# use UR/UE or MT/ME
if 'refuri' in node:
- self.ensure_c_eol() # c_eol avoids space before the refuri
+ self.ensure_c_eol() # c_eol avoids space before the refuri
_uri = node['refuri']
if _uri.startswith('mailto:'):
- _uri = _uri[7:] # remove "mailto:"
+ _uri = _uri[7:] # remove "mailto:"
# groff macro in an.tmac adds "mailto:"
# mandoc does not.
self.body.append(".MT ")
Modified: trunk/docutils/test/test_writers/test_manpage.py
===================================================================
--- trunk/docutils/test/test_writers/test_manpage.py 2025-05-01 10:01:14 UTC (rev 10119)
+++ trunk/docutils/test/test_writers/test_manpage.py 2025-05-05 13:51:57 UTC (rev 10120)
@@ -55,7 +55,6 @@
settings_overrides={
'_disable_config': True,
'strict_visitor': True,
- 'use_reference_macros': False,
}).decode()
self.assertEqual(case_expected, output)
@@ -69,7 +68,7 @@
settings_overrides={
'_disable_config': True,
'strict_visitor': True,
- 'macro_references': True,
+ 'text_references': False,
'output_encoding': "unicode",
})
self.assertEqual(case_expected, output)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins