man pages: add author section (#122)

This renders the authors (from the title block), if specified, into a
Authors section.

Signed-off-by: Miek Gieben <miek@miek.nl>

Author: miekg

Syntax.md

@@ -208,13 +208,15 @@ Title Block:
     * `area`, what is it, e.g. "User Commands".
     * `workgroup`, who wrote this e.g.  "Mmark Markdown".
     * `date`, date of the man page, optional, defaults to "today".
+    * `author`, to add an Authors section at the end.
 
 Images:
 :   See [Images in Mmark](/syntax/images) for details, `ascii-art` images from a sub-figure are
     included.
 
 References and citations:
-:   Supported, a "Bibliography" section is added.
+:   Supported, a "Bibliography" section is added. Note that unlike XML2RFC, references for IDs and
+    RFCs *are not* automatically added.
 
 Code Block:
 :   Tabs are converted into four spaces.

lang/lang.go

@@ -12,33 +12,36 @@ func New(language string) Lang {
 	// The keys must be in all lower case for normalized lookup.
 	l.m = map[string]Term{
 		"en": {
-			Footnotes:    "Footnotes",
+			And:          "and",
+			Authors:      "Authors",
 			Bibliography: "Bibliography",
+			Footnotes:    "Footnotes",
 			Index:        "Index",
+			WrittenBy:    "Written by",
 		},
 		"nl": {
-			Footnotes:    "Voetnoten",
 			Bibliography: "Bibliografie",
+			Footnotes:    "Voetnoten",
 			Index:        "Index",
 		},
 		"de": {
-			Footnotes:    "Fußnoten",
 			Bibliography: "Literaturverzeichnis",
+			Footnotes:    "Fußnoten",
 			Index:        "Index",
 		},
 		"ja": {
-			Footnotes:    "脚注",
 			Bibliography: "参考文献",
+			Footnotes:    "脚注",
 			Index:        "索引",
 		},
 		"zh-cn": {
-			Footnotes:    "注释",
 			Bibliography: "参考文献",
+			Footnotes:    "注释",
 			Index:        "索引",
 		},
 		"zh-tw": {
-			Footnotes:    "註釋",
 			Bibliography: "參考文獻",
+			Footnotes:    "註釋",
 			Index:        "索引",
 		},
 	}
@@ -55,9 +58,12 @@ type Lang struct {
 
 // Term contains the specific terms for translation.
 type Term struct {
-	Footnotes    string
+	And          string
+	Authors      string
 	Bibliography string
+	Footnotes    string
 	Index        string
+	WrittenBy    string
 }
 
 func (l Lang) Footnotes() string {
@@ -83,3 +89,27 @@ func (l Lang) Index() string {
 	}
 	return t.Index
 }
+
+func (l Lang) Authors() string {
+	t, ok := l.m[l.language]
+	if !ok {
+		return l.m["en"].Authors
+	}
+	return t.Authors
+}
+
+func (l Lang) And() string {
+	t, ok := l.m[l.language]
+	if !ok {
+		return l.m["en"].And
+	}
+	return t.And
+}
+
+func (l Lang) WrittenBy() string {
+	t, ok := l.m[l.language]
+	if !ok {
+		return l.m["en"].WrittenBy
+	}
+	return t.WrittenBy
+}

mast/authors.go

@@ -0,0 +1,10 @@
+package mast
+
+import (
+	"github.com/gomarkdown/markdown/ast"
+)
+
+// Authors represents markdown authors section node.
+type Authors struct {
+	ast.Container
+}

mmark.go

@@ -106,19 +106,6 @@ func main() {
 		}
 
 		doc := markdown.Parse(d, p)
-		if *flagBib {
-			mparser.AddBibliography(doc)
-		}
-		if *flagIndex {
-			mparser.AddIndex(doc)
-		}
-
-		if *flagAst {
-			ast.Print(os.Stdout, doc)
-			fmt.Print("\n")
-			return
-		}
-
 		if *flagMan {
 			title := false
 			// If there isn't a title block the resulting manual page does not start
@@ -136,8 +123,24 @@ func main() {
 				c := doc.GetChildren()
 				newc := append([]ast.Node{t}, c...)
 				doc.SetChildren(newc) // t must be the first element.
+			} else {
+				ast.AppendChild(doc, &mast.Authors{})
 			}
+
 		}
+		if *flagBib {
+			mparser.AddBibliography(doc)
+		}
+		if *flagIndex {
+			mparser.AddIndex(doc)
+		}
+
+		if *flagAst {
+			ast.Print(os.Stdout, doc)
+			fmt.Print("\n")
+			return
+		}
+
 		var renderer markdown.Renderer
 
 		switch {

render/man/authors.go

@@ -0,0 +1,58 @@
+package man
+
+import (
+	"io"
+	"strings"
+
+	"github.com/gomarkdown/markdown/ast"
+	"github.com/mmarkdown/mmark/mast"
+)
+
+// authors creates a 'Authors' section that can be included. Only the 'fullname' is used.
+// If not authors are specified, it will return nil.
+func (r *Renderer) authors(w io.Writer, _ *mast.Authors, entering bool) {
+	if !entering {
+		return
+	}
+	if r.Title == nil {
+		return
+	}
+	author := r.Title.TitleData.Author
+	if len(author) == 0 {
+		return
+	}
+
+	// create a node and call render on it.
+	node := &ast.Heading{Level: 1}
+	authors := r.opts.Language.Authors()
+	ast.AppendChild(node, &ast.Text{ast.Leaf{Literal: []byte(authors)}})
+	la := len(author)
+
+	// Needs to use the translation stuff
+	para := &ast.Paragraph{}
+	text := r.opts.Language.WrittenBy() + " "
+	// combine them with commas, add the last one with 'and'
+	switch la {
+	case 1:
+		text += author[0].Fullname
+	case 2:
+		text += author[0].Fullname + " " + r.opts.Language.And() + " " + author[1].Fullname
+	default:
+		names := make([]string, len(author))
+		for i, a := range author {
+			names[i] = a.Fullname
+		}
+		text += strings.Join(names[:len(names)-2], ", ")
+		text += " " + r.opts.Language.And() + " " + names[len(names)-1]
+	}
+	text += "."
+
+	ast.AppendChild(para, &ast.Text{ast.Leaf{Literal: []byte(text)}})
+	ast.AppendChild(node, para)
+
+	ast.WalkFunc(node, func(node ast.Node, entering bool) ast.WalkStatus {
+		return r.RenderNode(w, node, entering)
+	})
+
+	return
+}

render/man/renderer.go

@@ -47,6 +47,7 @@ type RendererOptions struct {
 type Renderer struct {
 	opts RendererOptions
 
+	Title        *mast.Title
 	listLevel    int
 	allListLevel int
 }
@@ -415,6 +416,9 @@ func (r *Renderer) RenderNode(w io.Writer, node ast.Node, entering bool) ast.Wal
 		// do nothing
 	case *mast.Title:
 		r.title(w, node, entering)
+		r.Title = node // save for later.
+	case *mast.Authors:
+		r.authors(w, node, entering)
 	case *mast.Bibliography:
 		if entering {
 			r.outs(w, "\n.SH \"")

render/markdown/renderer.go

@@ -648,6 +648,8 @@ func (r *Renderer) RenderNode(w io.Writer, node ast.Node, entering bool) ast.Wal
 		r.outs(w, node.Trigger)
 		r.outs(w, "\n")
 		r.newline(w)
+	case *mast.Authors:
+		// ignore
 	case *mast.Bibliography:
 	case *mast.BibliographyItem:
 	case *mast.DocumentIndex, *mast.IndexLetter, *mast.IndexItem, *mast.IndexSubItem, *mast.IndexLink:

render/xml/renderer.go

@@ -716,6 +716,8 @@ func (r *Renderer) RenderNode(w io.Writer, node ast.Node, entering bool) ast.Wal
 	case *mast.Title:
 		r.titleBlock(w, node)
 		r.title = true
+	case *mast.Authors:
+		// ignore
 	case *mast.Bibliography:
 		r.bibliography(w, node, entering)
 	case *mast.BibliographyItem: