Allow Cross Reference Suffix (#180)

* Allow Cross Reference Suffix

this allows setting the format attribute in a reference.

Waiting for gomarkdown/markdown#260

Signed-off-by: Miek Gieben <[email protected]>

* Update to latest markdown and fix code a little

Signed-off-by: Miek Gieben <[email protected]>

* Add test

Signed-off-by: Miek Gieben <[email protected]>

Signed-off-by: Miek Gieben <[email protected]>

Author: miekg

Syntax.md

@@ -671,6 +671,25 @@ or
 
 And then reference the same `(#myid)`, the formatter (`xml2rfc`) will do the right thing.
 
+#### Cross Reference Text Suffixes
+
+Just like [](#reference-text-suffices), you can add a suffix text to a reference, to influence how
+xml2rfc will render it, see <https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html#section-3.11>
+it will allow you to set the format attribute. The following is supported:
+
+* counter
+* title
+* default
+
+* `(#myid, use counter)` -> format="counter"
+* `(#myid, use title)` -> format="title"
+
+Translation of these strings _is_ supported for a few languages, `(#myid, gebruik titel)` (Dutch) is
+supported for instance.
+
+Also note these strings need to be literary typed as shown here (we may become more lenient in the
+future).
+
 ### Super- and Subscript
 
 For superscript use `^` and for subscripts use `~`. For example:

go.mod

@@ -4,6 +4,6 @@ go 1.13
 
 require (
 	github.com/BurntSushi/toml v1.2.0
-	github.com/gomarkdown/markdown v0.0.0-20220825072242-90efaac57fb4
+	github.com/gomarkdown/markdown v0.0.0-20220830015526-01a3c37d6f50
 	github.com/google/go-cmp v0.2.0
 )

go.sum

@@ -2,5 +2,7 @@ github.com/BurntSushi/toml v1.2.0 h1:Rt8g24XnyGTyglgET/PRUNlrUeu9F5L+7FilkXfZgs0
 github.com/BurntSushi/toml v1.2.0/go.mod h1:CxXYINrC8qIiEnFrOxCa7Jy5BFHlXnUU2pbicEuybxQ=
 github.com/gomarkdown/markdown v0.0.0-20220825072242-90efaac57fb4 h1:YOfiTywt9f60GzIFrnor09U0Q3PySmqnyIqvK0o6fzI=
 github.com/gomarkdown/markdown v0.0.0-20220825072242-90efaac57fb4/go.mod h1:JDGcbDT52eL4fju3sZ4TeHGsQwhG9nbDV21aMyhwPoA=
+github.com/gomarkdown/markdown v0.0.0-20220830015526-01a3c37d6f50 h1:tSuUky4sFWjiIIEOefDDBjx5BUIT3kZwcXHM2CNDdTk=
+github.com/gomarkdown/markdown v0.0.0-20220830015526-01a3c37d6f50/go.mod h1:JDGcbDT52eL4fju3sZ4TeHGsQwhG9nbDV21aMyhwPoA=
 github.com/google/go-cmp v0.2.0 h1:+dTQ8DZQJz0Mb/HjFlkptS1FeQ4cWSnN941F8aEG4SQ=
 github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M=

lang/lang.go

@@ -20,15 +20,21 @@ func New(language string) Lang {
 			WrittenBy:    "Written by",
 			See:          "see",
 			Section:      "section",
+			UseCounter:   "use counter",
+			UseTitle:     "use title",
 		},
 		"nl": {
+			And:          "en",
 			Bibliography: "Bibliografie",
 			Footnotes:    "Voetnoten",
 			Index:        "Index",
 			See:          "zie",
 			Section:      "sectie",
+			UseCounter:   "gebruik nummer",
+			UseTitle:     "gebruik titel",
 		},
 		"de": {
+			And:          "und",
 			Bibliography: "Literaturverzeichnis",
 			Footnotes:    "Fußnoten",
 			Index:        "Index",
@@ -71,9 +77,11 @@ type Term struct {
 	Index        string
 	WrittenBy    string
 
-	// The references
-	See     string
-	Section string
+	// for cross references
+	See        string
+	Section    string
+	UseCounter string
+	UseTitle   string
 }
 
 func (l Lang) Footnotes() string {
@@ -139,3 +147,19 @@ func (l Lang) Section() string {
 	}
 	return t.Section
 }
+
+func (l Lang) UseCounter() string {
+	t, ok := l.m[l.language]
+	if !ok {
+		return l.m["en"].UseCounter
+	}
+	return t.UseCounter
+}
+
+func (l Lang) UseTitle() string {
+	t, ok := l.m[l.language]
+	if !ok {
+		return l.m["en"].UseTitle
+	}
+	return t.UseTitle
+}

render/xml/renderer.go

@@ -567,7 +567,17 @@ func (r *Renderer) callout(w io.Writer, callout *ast.Callout) {
 
 func (r *Renderer) crossReference(w io.Writer, cr *ast.CrossReference, entering bool) {
 	if entering {
-		r.outTag(w, "<xref", []string{"target=\"" + string(cr.Destination) + "\""})
+		attr := []string{fmt.Sprintf(`target="%s"`, cr.Destination)}
+		if len(cr.Suffix) > 0 {
+			switch {
+			case string(cr.Suffix) == r.opts.Language.UseCounter():
+				attr = append(attr, `format="counter"`)
+
+			case string(cr.Suffix) == r.opts.Language.UseTitle():
+				attr = append(attr, `format="title"`)
+			}
+		}
+		r.outTag(w, "<xref", attr)
 		return
 	}
 	r.outs(w, "</xref>")

testdata/ref.md

@@ -0,0 +1 @@
+See (#myid, use counter), to check.

testdata/ref.xml

@@ -0,0 +1 @@
+<t>See <xref target="myid" format="counter"></xref>, to check.</t>