The branch, master has been updated
via 03fc62ad More man processing improvements
from 68c865c9 A few more man page script improvements.
https://git.samba.org/?p=rsync.git;a=shortlog;h=master
- Log -----------------------------------------------------------------
commit 03fc62ad2fcc065bcbe67ad4968b331f52189e26
Author: Wayne Davison <wa...@opencoder.net>
Date: Tue Jun 9 15:21:38 2020 -0700
More man processing improvements
- Support the commonmark library in addition to cmarkgfm.
- Remove github-flavor from the markup.
- A few more html style improvements.
-----------------------------------------------------------------------
Summary of changes:
NEWS.md | 4 +++
md2man | 84 ++++++++++++++++++++++++++++++++++++++------------------
rsync-ssl.1.md | 6 ++--
rsync.1.md | 29 ++++++++++---------
rsyncd.conf.5.md | 8 +++---
5 files changed, 82 insertions(+), 49 deletions(-)
Changeset truncated at 500 lines:
diff --git a/NEWS.md b/NEWS.md
index 783064ab..837775ef 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -126,6 +126,10 @@ Protocol: 31 (unchanged)
- Silenced some annoying warnings about major()|minor() due to the autoconf
include-file check not being smart enough.
+ - Converted the man pages from yodl to markdown. They are now processed via a
+ simple python3 script using the cmarkgfm OR commonmark library. This should
+ make it easier for packaging rsync, since yodl has gotten obscure.
+
- Improved some configure checks to work better with strict C99 compilers.
- The `--debug=FOO` options are no longer auto-forwarded to the server side,
diff --git a/md2man b/md2man
index 2c92fbe2..57840103 100755
--- a/md2man
+++ b/md2man
@@ -1,15 +1,15 @@
#!/usr/bin/python3
-# This script takes a manpage written in github-flavored markdown and turns it
-# into a html web page and a nroff man page. The input file must have the name
-# of the program and the section in the format: NAME.NUM.md. The output files
-# are written into the current directory named NAME.NUM.html and NAME.NUM. The
-# input format has one extra extension: if a numbered list starts at 0, it is
-# turned into a description list. The dl's dt tag is taken from the contents of
-# the first tag inside the li, which is usually a p tag or a code tag. The
-# cmarkgfm lib is used to transforms the input file into html. The html.parser
-# is used as a state machine that both tweaks the html and outputs the nroff
-# data based on the html tags.
+# This script takes a manpage written in markdown and turns it into an html web
+# page and a nroff man page. The input file must have the name of the program
+# and the section in this format: NAME.NUM.md. The output files are written
+# into the current directory named NAME.NUM.html and NAME.NUM. The input
+# format has one extra extension: if a numbered list starts at 0, it is turned
+# into a description list. The dl's dt tag is taken from the contents of the
+# first tag inside the li, which is usually a p, code, or strong tag. The
+# cmarkgfm or commonmark lib is used to transforms the input file into html.
+# The html.parser is used as a state machine that both tweaks the html and
+# outputs the nroff data based on the html tags.
#
# Copyright (C) 2020 Wayne Davison
#
@@ -23,16 +23,26 @@ CONSUMES_TXT = set('h1 h2 p li pre'.split())
HTML_START = """\
<html><head>
<title>%s</title>
-<link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap";
rel="stylesheet">
+<link
href="https://fonts.googleapis.com/css2?family=Roboto&family=Roboto+Mono&display=swap";
rel="stylesheet">
<style>
body {
- max-width: 40em;
+ max-width: 50em;
margin: auto;
font-size: 1.2em;
+}
+body, b, strong, u {
font-family: 'Roboto', sans-serif;
}
+code {
+ font-family: 'Roboto Mono', monospace;
+ font-weight: bold;
+}
+pre code {
+ display: block;
+ font-weight: normal;
+}
blockquote pre code {
- background: #eee;
+ background: #f1f1f1;
}
dd p:first-of-type {
margin-block-start: 0em;
@@ -47,7 +57,7 @@ HTML_END = """\
"""
MAN_START = r"""
-.TH "%s" "%s" "%s" "" ""
+.TH "%s" "%s" "%s" "%s" "User Commands"
""".lstrip()
MAN_END = """\
@@ -57,6 +67,8 @@ NORM_FONT = ('\1', r"\fP")
BOLD_FONT = ('\2', r"\fB")
ULIN_FONT = ('\3', r"\fI")
+md_parser = None
+
def main():
fi =
re.match(r'^(?P<fn>(?P<srcdir>.+/)?(?P<name>(?P<prog>[^/]+)\.(?P<sect>\d+))\.md)$',
args.mdfile)
if not fi:
@@ -93,10 +105,14 @@ def main():
break
with open(fi.fn, 'r', encoding='utf-8') as fh:
- txt = re.sub(r'@VERSION@', env_subs['VERSION'], fh.read())
- txt = re.sub(r'@LIBDIR@', env_subs['libdir'], txt)
- fi.html_in = cmarkgfm.github_flavored_markdown_to_html(txt)
- txt = None
+ txt = fh.read()
+
+ txt = re.sub(r'@VERSION@', env_subs['VERSION'], txt)
+ txt = re.sub(r'@LIBDIR@', env_subs['libdir'], txt)
+ fi.html_in = md_parser(txt)
+ txt = None
+
+ fi.man_headings = (fi.prog, fi.sect, fi.date, fi.prog + ' ' +
env_subs['VERSION'])
HtmlToManPage(fi)
@@ -109,6 +125,13 @@ def main():
with open(fn, 'w', encoding='utf-8') as fh:
fh.write(txt)
+def html_via_cmarkgfm(txt):
+ return cmarkgfm.markdown_to_html(txt)
+
+
+def html_via_commonmark(txt):
+ return commonmark.HtmlRenderer().render(commonmark.Parser().parse(txt))
+
class HtmlToManPage(HTMLParser):
def __init__(self, fi):
@@ -122,7 +145,7 @@ class HtmlToManPage(HTMLParser):
dt_from = None,
in_pre = False,
html_out = [ HTML_START % fi.title ],
- man_out = [ MAN_START % (fi.prog, fi.sect, fi.date) ],
+ man_out = [ MAN_START % fi.man_headings ],
txt = '',
)
@@ -171,9 +194,10 @@ class HtmlToManPage(HTMLParser):
st.man_out.append(st.p_macro + ".nf\n")
elif tag == 'code' and not st.in_pre:
st.txt += BOLD_FONT[0]
- elif tag == 'strong' or tag == 'bold':
+ elif tag == 'strong' or tag == 'b':
st.txt += BOLD_FONT[0]
- elif tag == 'i' or tag == 'em':
+ elif tag == 'em' or tag == 'i':
+ tag = 'u' # Change it into underline to be more like the man page
st.txt += ULIN_FONT[0]
elif tag == 'ol':
start = 1
@@ -236,11 +260,12 @@ class HtmlToManPage(HTMLParser):
st.in_pre = False
st.man_out.append(manify(txt) + "\n.fi\n")
elif tag == 'code' and not st.in_pre:
- add_to_txt = NORM_FONT[0]
- elif tag == 'strong' or tag == 'bold':
- add_to_txt = NORM_FONT[0]
- elif tag == 'i' or tag == 'em':
- add_to_txt = NORM_FONT[0]
+ add_to_txt = NORM_FONT[0]
+ elif tag == 'strong' or tag == 'b':
+ add_to_txt = NORM_FONT[0]
+ elif tag == 'em' or tag == 'i':
+ tag = 'u' # Change it into underline to be more like the man page
+ add_to_txt = NORM_FONT[0]
elif tag == 'ol' or tag == 'ul':
if st.list_state.pop() == 'dl':
tag = 'dl'
@@ -315,7 +340,12 @@ if __name__ == '__main__':
try:
import cmarkgfm
+ md_parser = html_via_cmarkgfm
except:
- die("The cmarkgfm library is not available for python3.")
+ try:
+ import commonmark
+ md_parser = html_via_commonmark
+ except:
+ die("Failed to find cmarkgfm or commonmark for python3.")
main()
diff --git a/rsync-ssl.1.md b/rsync-ssl.1.md
index 7b8f8b65..a57b5aca 100644
--- a/rsync-ssl.1.md
+++ b/rsync-ssl.1.md
@@ -68,7 +68,7 @@ The ssl helper scripts are affected by the following
environment variables:
# BUGS
-Please report bugs! See the web site at http://rsync.samba.org/
+Please report bugs! See the web site at <http://rsync.samba.org/>.
# VERSION
@@ -79,7 +79,7 @@ This man page is current for version @VERSION@ of rsync.
rsync is distributed under the GNU General Public License. See the file
COPYING for details.
-A WEB site is available at http://rsync.samba.org/ . The site includes an
+A web site is available at <http://rsync.samba.org/>. The site includes an
FAQ-O-Matic which may cover questions unanswered by this manual page.
# AUTHOR
@@ -87,4 +87,4 @@ FAQ-O-Matic which may cover questions unanswered by this
manual page.
This manpage was written by Wayne Davison.
Mailing lists for support and development are available at
-http://lists.samba.org .
+<http://lists.samba.org/>.
diff --git a/rsync.1.md b/rsync.1.md
index f32713f3..40a07331 100644
--- a/rsync.1.md
+++ b/rsync.1.md
@@ -3854,7 +3854,7 @@ values
see also the comments on the `--delete` option
-Please report bugs! See the web site at http://rsync.samba.org/
+Please report bugs! See the web site at <http://rsync.samba.org/>.
# VERSION
@@ -3874,17 +3874,16 @@ that can be used with a restricted ssh login.
rsync is distributed under the GNU General Public License. See the file
COPYING for details.
-A WEB site is available at http://rsync.samba.org/ . The
-site includes an FAQ-O-Matic which may cover questions unanswered by this
-manual page.
+A web site is available at <http://rsync.samba.org/>. The site includes an
+FAQ-O-Matic which may cover questions unanswered by this manual page.
-The primary ftp site for rsync is ftp://rsync.samba.org/pub/rsync .
+The primary ftp site for rsync is <ftp://rsync.samba.org/pub/rsync>
-We would be delighted to hear from you if you like this program.
-Please contact the mailing-list at rs...@lists.samba.org.
+We would be delighted to hear from you if you like this program. Please
+contact the mailing-list at <rs...@lists.samba.org>.
-This program uses the excellent zlib compression library written by
-Jean-loup Gailly and Mark Adler.
+This program uses the excellent zlib compression library written by Jean-loup
+Gailly and Mark Adler.
# THANKS
@@ -3892,14 +3891,14 @@ Special thanks go out to: John Van Essen, Matt
McCutchen, Wesley W. Terpstra,
David Dykstra, Jos Backus, Sebastian Krahmer, Martin Pool, and our
gone-but-not-forgotten compadre, J.W. Schultz.
-Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell
-and David Bell. I've probably missed some people, my apologies if I have.
+Thanks also to Richard Brent, Brendan Mackay, Bill Waite, Stephen Rothwell and
+David Bell. I've probably missed some people, my apologies if I have.
# AUTHOR
-rsync was originally written by Andrew Tridgell and Paul Mackerras.
-Many people have later contributed to it. It is currently maintained
-by Wayne Davison.
+rsync was originally written by Andrew Tridgell and Paul Mackerras. Many
+people have later contributed to it. It is currently maintained by Wayne
+Davison.
Mailing lists for support and development are available at
-http://lists.samba.org .
+<http://lists.samba.org/>.
diff --git a/rsyncd.conf.5.md b/rsyncd.conf.5.md
index ff946261..41b64e78 100644
--- a/rsyncd.conf.5.md
+++ b/rsyncd.conf.5.md
@@ -1092,7 +1092,7 @@ The /etc/rsyncd.secrets file would look something like
this:
# BUGS
Please report bugs! The rsync bug tracking system is online at
-http://rsync.samba.org/ .
+<http://rsync.samba.org/>.
# VERSION
@@ -1103,9 +1103,9 @@ This man page is current for version @VERSION@ of rsync.
rsync is distributed under the GNU General Public License. See the file
COPYING for details.
-The primary ftp site for rsync is ftp://rsync.samba.org/pub/rsync .
+The primary ftp site for rsync is <ftp://rsync.samba.org/pub/rsync>
-A WEB site is available at http://rsync.samba.org/ .
+A web site is available at <http://rsync.samba.org/>.
We would be delighted to hear from you if you like this program.
@@ -1123,4 +1123,4 @@ rsync was written by Andrew Tridgell and Paul Mackerras.
Many people have
later contributed to it.
Mailing lists for support and development are available at
-http://lists.samba.org .
+<http://lists.samba.org/>.
--
The rsync repository.
_______________________________________________
rsync-cvs mailing list
rsync-cvs@lists.samba.org
https://lists.samba.org/mailman/listinfo/rsync-cvs
