SF.net SVN: docutils:[9889 ] trunk/sandbox/manpage-wri ter
grubert--- via Docutils-checkins <[email protected]>
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 9889
http://sourceforge.net/p/docutils/code/9889
Author: grubert
Date: 2024-08-13 10:25:04 +0000 (Tue, 13 Aug 2024)
Log Message:
-----------
rename README and TODO to rst
Added Paths:
-----------
trunk/sandbox/manpage-writer/README.rst
trunk/sandbox/manpage-writer/TODO.rst
Removed Paths:
-------------
trunk/sandbox/manpage-writer/README.txt
trunk/sandbox/manpage-writer/TODO.txt
Copied: trunk/sandbox/manpage-writer/README.rst (from rev 9888, trunk/sandbox/manpage-writer/README.txt)
===================================================================
--- trunk/sandbox/manpage-writer/README.rst (rev 0)
+++ trunk/sandbox/manpage-writer/README.rst 2024-08-13 10:25:04 UTC (rev 9889)
@@ -0,0 +1,59 @@
+===================
+ Manpage test area
+===================
+
+.. note::
+
+ New semantic format mdoc https://mandoc.bsd.lv/
+
+Additionally to standard testing, here we try to include tests that process
+the generated man pages and verify the output.
+
+Some of these tests either require roff and some groff to verify the produced layout.
+
+From the groff-manual at gnu.org
+--------------------------------
+
+5.1.6 Input Conventions
+
+Since gtroff does filling automatically, it is traditional in groff not to try
+and type things in as nicely formatted paragraphs.
+
+: this conflicts with reST because a reST-document is nicely formatted WYSIWYH.
+
+These are some conventions commonly used when typing gtroff text:
+
+* Break lines after punctuation, particularly at the end of a sentence and in
+ other logical places. Keep separate phrases on lines by themselves, as entire
+ phrases are often added or deleted when editing.
+
+* Try to keep lines less than 40–60 characters, to allow space for inserting
+ more text.
+
+* Do not try to do any formatting in a WYSIWYG manner (i.e., don’t try using
+ spaces to get proper indentation).
+
+5.1.3 Sentences
+
+Although it is often debated, some typesetting rules say there should be
+different amounts of space after various punctuation marks. For example, the
+Chicago typesetting manual says that a period at the end of a sentence should
+have twice as much space following it as would a comma or a period as part of
+an abbreviation.
+
+gtroff does this by flagging certain characters (normally ‘!’, ‘?’, and ‘.’) as
+end-of-sentence characters. When gtroff encounters one of these characters at
+the end of a line, it appends a normal space followed by a sentence space in
+the formatted output. (This justifies one of the conventions mentioned in Input
+Conventions.)
+
+In addition, the following characters and symbols are treated transparently
+while handling end-of-sentence characters: ‘"’, ‘'’, ‘)’, ‘]’, ‘*’, \[dg],
+\[rq], and \[cq].
+
+See the cflags request in Using Symbols, for more details.
+
+To prevent the insertion of extra space after an end-of-sentence character (at
+the end of a line), append \&.
+
+
Deleted: trunk/sandbox/manpage-writer/README.txt
===================================================================
--- trunk/sandbox/manpage-writer/README.txt 2024-08-13 10:18:46 UTC (rev 9888)
+++ trunk/sandbox/manpage-writer/README.txt 2024-08-13 10:25:04 UTC (rev 9889)
@@ -1,59 +0,0 @@
-===================
- Manpage test area
-===================
-
-.. note::
-
- New semantic format mdoc https://mandoc.bsd.lv/
-
-Additionally to standard testing, here we try to include tests that process
-the generated man pages and verify the output.
-
-Some of these tests either require roff and some groff to verify the produced layout.
-
-From the groff-manual at gnu.org
---------------------------------
-
-5.1.6 Input Conventions
-
-Since gtroff does filling automatically, it is traditional in groff not to try
-and type things in as nicely formatted paragraphs.
-
-: this conflicts with reST because a reST-document is nicely formatted WYSIWYH.
-
-These are some conventions commonly used when typing gtroff text:
-
-* Break lines after punctuation, particularly at the end of a sentence and in
- other logical places. Keep separate phrases on lines by themselves, as entire
- phrases are often added or deleted when editing.
-
-* Try to keep lines less than 40–60 characters, to allow space for inserting
- more text.
-
-* Do not try to do any formatting in a WYSIWYG manner (i.e., don’t try using
- spaces to get proper indentation).
-
-5.1.3 Sentences
-
-Although it is often debated, some typesetting rules say there should be
-different amounts of space after various punctuation marks. For example, the
-Chicago typesetting manual says that a period at the end of a sentence should
-have twice as much space following it as would a comma or a period as part of
-an abbreviation.
-
-gtroff does this by flagging certain characters (normally ‘!’, ‘?’, and ‘.’) as
-end-of-sentence characters. When gtroff encounters one of these characters at
-the end of a line, it appends a normal space followed by a sentence space in
-the formatted output. (This justifies one of the conventions mentioned in Input
-Conventions.)
-
-In addition, the following characters and symbols are treated transparently
-while handling end-of-sentence characters: ‘"’, ‘'’, ‘)’, ‘]’, ‘*’, \[dg],
-\[rq], and \[cq].
-
-See the cflags request in Using Symbols, for more details.
-
-To prevent the insertion of extra space after an end-of-sentence character (at
-the end of a line), append \&.
-
-
Copied: trunk/sandbox/manpage-writer/TODO.rst (from rev 9888, trunk/sandbox/manpage-writer/TODO.txt)
===================================================================
--- trunk/sandbox/manpage-writer/TODO.rst (rev 0)
+++ trunk/sandbox/manpage-writer/TODO.rst 2024-08-13 10:25:04 UTC (rev 9889)
@@ -0,0 +1,261 @@
+TODOs
+=====
+
+:Date: $Date$
+
+* lines starting with a ``{not typeset} abc``
+
+# #480 document information comment with docutils version
+
+* #481 no uppercasing of titles (config option)
+
+* #482 no default formatting ... use macros or leave to writer
+
+* How to typeset command/manpage names in text.
+
+ There are conflicting traditions and conventions on these points.
+ groff_man_style(7) has recommendations.
+
+ Use bold for literal portions of syntax synopses, for
+ command‐line options in running text, and for literals
+ that are major topics of the subject under discussion; for
+ example, this page uses bold for macro, string, and
+ register names. In an .EX/.EE example of interactive I/O
+ (such as a shell session), set only user input in bold.
+
+ Use italics for file and path names, for environment
+ variables, for C data types, for enumeration or
+ preprocessor constants in C, for variant (user‐
+ replaceable) portions of syntax synopses, for the first
+ occurrence (only) of a technical concept being introduced,
+ for names of journals and of literary works longer than an
+ article, and anywhere a parameter requiring replacement by
+ the user is encountered. An exception involves variant
+ text in a context already typeset in italics, such as file
+ or path names with replaceable components; in such cases,
+ follow the convention of mathematical typography: set the
+ file or path name in italics as usual but use roman for
+ the variant part (see .IR and .RI below), and italics
+ again in running roman text when referring to the variant
+ material.
+
+ Plan 9 from User Space troff and groff 1.23.0 support an ``MR`` macro
+ for the specific purpose of setting man page cross references. It is
+ reasonable to assume that groff 1.23.0 has not propagated yet to every
+ platform Python docutils would like to support yet. You can wait
+ until it has, or supply a fallback definition in the man(7) documents
+ you generate. ::
+
+ .\" Define fallback for groff 1.23's MR macro if the system lacks it.
+ .nr df 0 \" do fallback?
+ .if !\n(.f .nr df 1 \" mandoc
+ .if \n(.g .if !d MR .nr df 1 \" older groff
+ .if !\n(.g .nr df 1 \" non-groff *roff
+ .if \n(df \{\
+ .de MR
+ .ie \\n(.$=1 \
+ .I \%\\$1
+ .el \
+ .IR \%\\$1 (\\$2)\\$3
+ ..
+ .\}
+ .rr df
+
+see groff_man_style ::
+
+ .SH "See also"
+ .
+ .MR \%tbl 1 ,
+ .MR \%eqn 1 ,
+ and
+ .MR \%refer 1
+ are preprocessors used with man pages.
+ .
+ .MR man 1
+ describes the man page librarian on your system.
+
+but the rST source would be more like this ::
+
+ See also
+ ========
+
+ tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.
+ man(1) describes the man page ...
+
+so the MR things need to be found with regexp or marked with a role/directive ?
+or a reference type man:tbl(1)
+
+The ``\%`` is :
+
+ a word may be broken at hyphens, at ``\%`` or ``\:`` escape sequences
+
+whatfore at the word start ?
+
+Branden writes:
+
+ You will not need to generate the arguments to the MR macro with a leading
+ \% escape sequence. ... see feature request #107
+
+groff_man_style on
+
+ Hyperlink macros
+ Man page cross references like ls(1) are best presented with .MR. Text may be
+ hyperlinked to email addresses with .MT/.ME or other URIs with .UR/.UE. Hyper‐
+ linked text is supported on HTML and terminal output devices; terminals and
+ pager programs must support ECMA-48 OSC 8 escape sequences (see grotty(1)).
+ When device support is unavailable or disabled with the U register (see section
+ “Options” below), .MT and .UR URIs are rendered between angle brackets after the
+ linked text.
+
+ .MT, .ME, .UR, and .UE are GNU extensions not defined on systems running AT&T,
+ Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below. Plan 9 from
+ User Space's troff implements .MR.
+
+ The arguments to .MR, .MT, and .UR should be prepared for typesetting since they
+ can appear in the output. Use special character escape sequences to encode Uni‐
+ code basic Latin characters where necessary, particularly the hyphen-minus.
+ (See section “Portability” below.) URIs can be lengthy; rendering them can re‐
+ sult in jarring adjustment or variations in line length, or troff warnings when
+ a hyperlink is longer than an output line. The application of non-printing
+ break point escape sequences \: after each slash (or series thereof), and before
+ each dot (or series thereof) is recommended as a rule of thumb. The former
+ practice avoids forcing a trailing slash in a URI onto a separate output line,
+ and the latter helps the reader to avoid mistakenly interpreting a dot at the
+ end of a line as a period (or multiple dots as an ellipsis). Thus,
+ .UR http://\:example\:.com/\:fb8afcfbaebc74e\:.cc
+ has several potential break points in the URI shown. Consider adding break
+ points before or after at signs in email addresses, and question marks, amper‐
+ sands, and number signs in HTTP(S) URIs. The formatter removes \: escape se‐
+ quences from hyperlinks when supplying device control commands to output dri‐
+ vers.
+
+
+Used macros ... to be completed
+-------------------------------
+
+ .TP [indentation]
+ Set a paragraph with a leading tag, and the remainder of the paragraph
+ indented. A one-line input trap is planted; text on the next line, which
+ can be formatted with a macro, becomes the tag, which is placed at the
+ current left margin. The tag can be extended with the \c escape se‐
+ quence. Subsequent text is indented by indentation, if specified, and by
+ the amount of the IN register otherwise. If the tag is not as wide as
+ the indentation, the paragraph starts on the same line as the tag, at the
+ applicable indentation, and continues on the following lines. Otherwise,
+ the descriptive part of the paragraph begins on the line following the
+ tag.
+
+ .TQ Set an additional tag for a paragraph tagged with .TP. An input trap is
+ planted as with .TP.
+
+ This macro is a GNU extension not defined on systems running AT&T,
+ Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below.
+
+
+
+Notes
+-----
+
+* Images and equations are discouraged.
+
+* Lists in admonitions are not intended.
+
+Discussions
+-----------
+
+* Encoding declaration ``'\" t -*- coding: ISO-8859-1 -*-``
+ in first line.
+
+ The part after ``t`` is a GNU Emacs convention. A *groff* program
+ called *preconv*\(1) understands it, but GNU *troff*\(1) itself does
+ not.
+
+ The ``t`` is part of a *man*\(1) convention; GNU *troff*\(1) doesn't
+ understand it, either (but since *tbl*\(1) is a *roff* preprocessor,
+ it's too late by the time ``troff`` sees the input anyway).
+
+* BUT if UTF-8 is declared tables are no longer processed.
+
+* BUT we have a comment there and the macros following it
+
+* Input and output encoding are problematic at least.
+
+* input/optionstoo.txt:23: (ERROR/3) Unexpected indentation.
+ is what it is ... leave it so.
+
+ TODO the curly brace on start of line hides the line
+
+* doublespace after end of sentence in manpages ?
+
+ see https://sourceforge.net/p/docutils/bugs/427/
+
+ Chicago manual of style ... hard to automate.
+
+Check ``docs/user/manpage.txt``
+
+* escape double quotes in macro arguments ?
+
+ Use the special character escape sequence ``\(dq``.
+ groff_man_style(7) explains.
+
+ \(dq Basic Latin quotation mark (double quote). Use in macro
+ calls to prevent ‘"” from being interpreted as beginning a
+ quoted argument, or simply for readability.
+
+ .TP
+ .BI "split \(dq" text \(dq
+
+* How to write long syntax lines.
+
+ groff_man_style(7) explains.::
+
+ \newline
+ Join the next input line to the current one. Except for
+ the update of the input line counter (used for diagnostic
+ messages and related purposes), a series of lines ending
+ in backslash‐newline appears to groff as a single input
+ line. Use this escape sequence to split excessively long
+ input lines for document maintenance.
+
+* Line ends around email or web addresses in texts.
+
+ The ``UE`` and ``ME`` macros accept an argument, which is appended to
+ the link text without intervening space.
+
+ groff_man_style(7) explains.
+
+ \c End a text line without inserting space or attempting a
+ break. Normally, if filling is enabled, the end of a text
+ line is treated like a space; an output line may be broken
+ there (if not, an adjustable space is inserted); if
+ filling is disabled, the line will be broken there, as in
+ .EX/.EE examples. The next line is interpreted as usual
+ and can include a macro call (contrast with \newline). \c
+ is useful when three font styles are needed in a single
+ word, as in a command synopsis.
+
+ .RB [ \-\-stylesheet=\c
+ .IR name ]
+
+ It also helps when changing font styles in .EX/.EE
+ examples, since they are not filled.
+
+ .EX
+ $ \c
+ .B groff \-T utf8 \-Z \c
+ .I file \c
+ .B | grotty \-i
+ .EE
+
+ Here's an example using groff's ``MT`` and ``ME`` macros.::
+
+ Mail the maintainer (\c
+ .MT [email protected]
+ Arthur Pewtey
+ .ME )
+ to submit patches.
+
+ How to distinguish something is inline or not in the writer
+ so to maybe put long urls after the current paragraph ?
+
+
Deleted: trunk/sandbox/manpage-writer/TODO.txt
===================================================================
--- trunk/sandbox/manpage-writer/TODO.txt 2024-08-13 10:18:46 UTC (rev 9888)
+++ trunk/sandbox/manpage-writer/TODO.txt 2024-08-13 10:25:04 UTC (rev 9889)
@@ -1,261 +0,0 @@
-TODOs
-=====
-
-:Date: $Date$
-
-* lines starting with a ``{not typeset} abc``
-
-# #480 document information comment with docutils version
-
-* #481 no uppercasing of titles (config option)
-
-* #482 no default formatting ... use macros or leave to writer
-
-* How to typeset command/manpage names in text.
-
- There are conflicting traditions and conventions on these points.
- groff_man_style(7) has recommendations.
-
- Use bold for literal portions of syntax synopses, for
- command‐line options in running text, and for literals
- that are major topics of the subject under discussion; for
- example, this page uses bold for macro, string, and
- register names. In an .EX/.EE example of interactive I/O
- (such as a shell session), set only user input in bold.
-
- Use italics for file and path names, for environment
- variables, for C data types, for enumeration or
- preprocessor constants in C, for variant (user‐
- replaceable) portions of syntax synopses, for the first
- occurrence (only) of a technical concept being introduced,
- for names of journals and of literary works longer than an
- article, and anywhere a parameter requiring replacement by
- the user is encountered. An exception involves variant
- text in a context already typeset in italics, such as file
- or path names with replaceable components; in such cases,
- follow the convention of mathematical typography: set the
- file or path name in italics as usual but use roman for
- the variant part (see .IR and .RI below), and italics
- again in running roman text when referring to the variant
- material.
-
- Plan 9 from User Space troff and groff 1.23.0 support an ``MR`` macro
- for the specific purpose of setting man page cross references. It is
- reasonable to assume that groff 1.23.0 has not propagated yet to every
- platform Python docutils would like to support yet. You can wait
- until it has, or supply a fallback definition in the man(7) documents
- you generate. ::
-
- .\" Define fallback for groff 1.23's MR macro if the system lacks it.
- .nr df 0 \" do fallback?
- .if !\n(.f .nr df 1 \" mandoc
- .if \n(.g .if !d MR .nr df 1 \" older groff
- .if !\n(.g .nr df 1 \" non-groff *roff
- .if \n(df \{\
- .de MR
- .ie \\n(.$=1 \
- .I \%\\$1
- .el \
- .IR \%\\$1 (\\$2)\\$3
- ..
- .\}
- .rr df
-
-see groff_man_style ::
-
- .SH "See also"
- .
- .MR \%tbl 1 ,
- .MR \%eqn 1 ,
- and
- .MR \%refer 1
- are preprocessors used with man pages.
- .
- .MR man 1
- describes the man page librarian on your system.
-
-but the rST source would be more like this ::
-
- See also
- ========
-
- tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.
- man(1) describes the man page ...
-
-so the MR things need to be found with regexp or marked with a role/directive ?
-or a reference type man:tbl(1)
-
-The ``\%`` is :
-
- a word may be broken at hyphens, at ``\%`` or ``\:`` escape sequences
-
-whatfore at the word start ?
-
-Branden writes:
-
- You will not need to generate the arguments to the MR macro with a leading
- \% escape sequence. ... see feature request #107
-
-groff_man_style on
-
- Hyperlink macros
- Man page cross references like ls(1) are best presented with .MR. Text may be
- hyperlinked to email addresses with .MT/.ME or other URIs with .UR/.UE. Hyper‐
- linked text is supported on HTML and terminal output devices; terminals and
- pager programs must support ECMA-48 OSC 8 escape sequences (see grotty(1)).
- When device support is unavailable or disabled with the U register (see section
- “Options” below), .MT and .UR URIs are rendered between angle brackets after the
- linked text.
-
- .MT, .ME, .UR, and .UE are GNU extensions not defined on systems running AT&T,
- Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below. Plan 9 from
- User Space's troff implements .MR.
-
- The arguments to .MR, .MT, and .UR should be prepared for typesetting since they
- can appear in the output. Use special character escape sequences to encode Uni‐
- code basic Latin characters where necessary, particularly the hyphen-minus.
- (See section “Portability” below.) URIs can be lengthy; rendering them can re‐
- sult in jarring adjustment or variations in line length, or troff warnings when
- a hyperlink is longer than an output line. The application of non-printing
- break point escape sequences \: after each slash (or series thereof), and before
- each dot (or series thereof) is recommended as a rule of thumb. The former
- practice avoids forcing a trailing slash in a URI onto a separate output line,
- and the latter helps the reader to avoid mistakenly interpreting a dot at the
- end of a line as a period (or multiple dots as an ellipsis). Thus,
- .UR http://\:example\:.com/\:fb8afcfbaebc74e\:.cc
- has several potential break points in the URI shown. Consider adding break
- points before or after at signs in email addresses, and question marks, amper‐
- sands, and number signs in HTTP(S) URIs. The formatter removes \: escape se‐
- quences from hyperlinks when supplying device control commands to output dri‐
- vers.
-
-
-Used macros ... to be completed
--------------------------------
-
- .TP [indentation]
- Set a paragraph with a leading tag, and the remainder of the paragraph
- indented. A one-line input trap is planted; text on the next line, which
- can be formatted with a macro, becomes the tag, which is placed at the
- current left margin. The tag can be extended with the \c escape se‐
- quence. Subsequent text is indented by indentation, if specified, and by
- the amount of the IN register otherwise. If the tag is not as wide as
- the indentation, the paragraph starts on the same line as the tag, at the
- applicable indentation, and continues on the following lines. Otherwise,
- the descriptive part of the paragraph begins on the line following the
- tag.
-
- .TQ Set an additional tag for a paragraph tagged with .TP. An input trap is
- planted as with .TP.
-
- This macro is a GNU extension not defined on systems running AT&T,
- Plan 9, or Solaris troff; see an-ext.tmac in section “Files” below.
-
-
-
-Notes
------
-
-* Images and equations are discouraged.
-
-* Lists in admonitions are not intended.
-
-Discussions
------------
-
-* Encoding declaration ``'\" t -*- coding: ISO-8859-1 -*-``
- in first line.
-
- The part after ``t`` is a GNU Emacs convention. A *groff* program
- called *preconv*\(1) understands it, but GNU *troff*\(1) itself does
- not.
-
- The ``t`` is part of a *man*\(1) convention; GNU *troff*\(1) doesn't
- understand it, either (but since *tbl*\(1) is a *roff* preprocessor,
- it's too late by the time ``troff`` sees the input anyway).
-
-* BUT if UTF-8 is declared tables are no longer processed.
-
-* BUT we have a comment there and the macros following it
-
-* Input and output encoding are problematic at least.
-
-* input/optionstoo.txt:23: (ERROR/3) Unexpected indentation.
- is what it is ... leave it so.
-
- TODO the curly brace on start of line hides the line
-
-* doublespace after end of sentence in manpages ?
-
- see https://sourceforge.net/p/docutils/bugs/427/
-
- Chicago manual of style ... hard to automate.
-
-Check ``docs/user/manpage.txt``
-
-* escape double quotes in macro arguments ?
-
- Use the special character escape sequence ``\(dq``.
- groff_man_style(7) explains.
-
- \(dq Basic Latin quotation mark (double quote). Use in macro
- calls to prevent ‘"” from being interpreted as beginning a
- quoted argument, or simply for readability.
-
- .TP
- .BI "split \(dq" text \(dq
-
-* How to write long syntax lines.
-
- groff_man_style(7) explains.::
-
- \newline
- Join the next input line to the current one. Except for
- the update of the input line counter (used for diagnostic
- messages and related purposes), a series of lines ending
- in backslash‐newline appears to groff as a single input
- line. Use this escape sequence to split excessively long
- input lines for document maintenance.
-
-* Line ends around email or web addresses in texts.
-
- The ``UE`` and ``ME`` macros accept an argument, which is appended to
- the link text without intervening space.
-
- groff_man_style(7) explains.
-
- \c End a text line without inserting space or attempting a
- break. Normally, if filling is enabled, the end of a text
- line is treated like a space; an output line may be broken
- there (if not, an adjustable space is inserted); if
- filling is disabled, the line will be broken there, as in
- .EX/.EE examples. The next line is interpreted as usual
- and can include a macro call (contrast with \newline). \c
- is useful when three font styles are needed in a single
- word, as in a command synopsis.
-
- .RB [ \-\-stylesheet=\c
- .IR name ]
-
- It also helps when changing font styles in .EX/.EE
- examples, since they are not filled.
-
- .EX
- $ \c
- .B groff \-T utf8 \-Z \c
- .I file \c
- .B | grotty \-i
- .EE
-
- Here's an example using groff's ``MT`` and ``ME`` macros.::
-
- Mail the maintainer (\c
- .MT [email protected]
- Arthur Pewtey
- .ME )
- to submit patches.
-
- How to distinguish something is inline or not in the writer
- so to maybe put long urls after the current paragraph ?
-
-
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