SF.net SVN: docutils:[9897 ] trunk

Revision: 9897
          http://sourceforge.net/p/docutils/code/9897
Author:   grubert
Date:     2024-08-14 09:18:20 +0000 (Wed, 14 Aug 2024)
Log Message:
-----------
change command line option --use-macro-references to the pair
--macro-references/--text-references to enable/disable usage 
of *man* macros .UR/.UE.

Modified Paths:
--------------
    trunk/docutils/HISTORY.txt
    trunk/docutils/docs/user/manpage.txt
    trunk/docutils/docutils/writers/manpage.py
    trunk/sandbox/manpage-writer/runtest
    trunk/sandbox/manpage-writer/runtest-mandoc

Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt	2024-08-14 08:11:48 UTC (rev 9896)
+++ trunk/docutils/HISTORY.txt	2024-08-14 09:18:20 UTC (rev 9897)
@@ -165,8 +165,8 @@
     docutils version in header
   - Stop converting text to full capitals (bug #481).
   - Add module function insert_URI_breakpoints.
-  - Add command line option ``--use-reference-macros`` to enable usage of man
-    macros .UR/.UE.
+  - Add command line option ``--macro-references``/``--text-references``
+    to enable/disable usage of *man* macros .UR/.UE.
 
 * docutils/writers/null.py
 

Modified: trunk/docutils/docs/user/manpage.txt
===================================================================
--- trunk/docutils/docs/user/manpage.txt	2024-08-14 08:11:48 UTC (rev 9896)
+++ trunk/docutils/docs/user/manpage.txt	2024-08-14 09:18:20 UTC (rev 9897)
@@ -107,6 +107,45 @@
 *man*\(1) or *gman*\(1), explains the sectional organization of the
 manuals (in both senses).
 
+
+Configuration
+'''''''''''''
+
+Options can be specified as
+
+* command-line options, or
+
+* configuration settings.
+
+Run ``rst2man --help`` to get a list of available options;
+see `Docutils Configuration`_ for details.
+
+.. _Docutils Configuration: config.html
+
+Option ``text-references``, ``macro-references`` set the way
+URI-references are typeset in the generated man page.
+
+``text-references``: is the default (for now). A URI-reference would be
+    typeset::
+
+      see Linux Man Page Howto <https://tldp.org/HOWTO/Man-Page/>
+
+``macro-references``: This results in the usage of *man*-macros for
+    URI-references::
+
+      see
+      .UR https://tldp.org/HOWTO/Man-Page/
+      Linux Man Page Howto
+      .UE
+
+    The the actual typesetting is done by man/roff/mandoc.
+
+    In groff 1.23 the macros support OSC8 output, to notify terminals that
+    some text is a link, similar to html ``<a ref="abc.html">abc</a>``,
+    ``abc.html`` then wouldn't be visible to the user but the terminal
+    offers opening the standard browser to that URI ... assuming OSC8 is
+    supported.
+
 References
 ''''''''''
 

Modified: trunk/docutils/docutils/writers/manpage.py
===================================================================
--- trunk/docutils/docutils/writers/manpage.py	2024-08-14 08:11:48 UTC (rev 9896)
+++ trunk/docutils/docutils/writers/manpage.py	2024-08-14 09:18:20 UTC (rev 9897)
@@ -116,11 +116,16 @@
     settings_spec = (
         'Manpage-Specific Options',
         None,
-        (('Use man macros .UR/.UE and .MT/.ME for references '
-          'or put references in plain text form.',
-          ['--use-reference-macros'],
-          {'default': False, 'action': 'store_true',
+        (('Use man macros .UR/.UE and .MT/.ME for references ',
+          ['--macro-references'],
+          {'dest': 'use_reference_macros',
+           'default': False, 'action': 'store_true',
            'validator': frontend.validate_boolean}),
+         ('Put references in plain text form.',
+          ['--text-references'],
+          {'dest': 'use_reference_macros',
+           'action': 'store_false',
+           'validator': frontend.validate_boolean}),
          ),
         )
 

Modified: trunk/sandbox/manpage-writer/runtest
===================================================================
--- trunk/sandbox/manpage-writer/runtest	2024-08-14 08:11:48 UTC (rev 9896)
+++ trunk/sandbox/manpage-writer/runtest	2024-08-14 09:18:20 UTC (rev 9897)
@@ -102,7 +102,7 @@
 for EXP_F in $EXP_DIR/*$EXT ; do
   BASE=`basename $EXP_F`
   F_BASE=${BASE%$EXT}
-  OPT="--use-reference-macros"
+  OPT="--macro-references"
   $CMD $OPT $IN_DIR/$F_BASE.txt $OUT_DIR/$BASE
   if [ $? -eq 0 ] ; then
     diff -s -u $EXP_DIR/$BASE $OUT_DIR/$BASE

Modified: trunk/sandbox/manpage-writer/runtest-mandoc
===================================================================
--- trunk/sandbox/manpage-writer/runtest-mandoc	2024-08-14 08:11:48 UTC (rev 9896)
+++ trunk/sandbox/manpage-writer/runtest-mandoc	2024-08-14 09:18:20 UTC (rev 9897)
@@ -103,7 +103,7 @@
 for EXP_F in $EXP_DIR/*$EXT ; do
   BASE=`basename $EXP_F`
   F_BASE=${BASE%$EXT}
-  OPT="--use-reference-macros"
+  OPT="--macro-references"
   $CMD $OPT $IN_DIR/$F_BASE.txt $OUT_DIR/$BASE
   if [ $? -eq 0 ] ; then
     diff -s -u $EXP_DIR/$BASE $OUT_DIR/$BASE

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.