error positions

Author: mandelsoft

Makefile

@@ -11,10 +11,10 @@ GOPATH                                         := $(shell go env GOPATH)
 
 NOW         := $(shell date -u +%FT%T%z)
 BUILD_FLAGS := "-s -w \
- -X github.com/mandelsoft/mdref/version.gitVersion=$(EFFECTIVE_VERSION) \
- -X github.com/mandelsoft/mdref/version.gitTreeState=$(GIT_TREE_STATE) \
- -X github.com/mandelsoft/mdref/version.gitCommit=$(COMMIT) \
- -X github.com/mandelsoft/mdref/version.buildDate=$(NOW)"
+ -X main.gitVersion=$(EFFECTIVE_VERSION) \
+ -X main.gitTreeState=$(GIT_TREE_STATE) \
+ -X main.gitCommit=$(COMMIT) \
+ -X main.buildDate=$(NOW)"
 
 build: ${SOURCES}
 	mkdir -p bin

README.md

@@ -5,12 +5,13 @@ This markdown reference generator uses
 a document tree with markdown files containing
 a special annotation syntax for tags and references
 as input and generates an appropriate target tree with
-references resolved to resolved Markdown links
+references resolved to consistent Markdown links
 and anchors.
 
-- Never fix heading anymore with corrupting links all over the document tree
+- Never fix headings anymore with corrupting links all over the document tree
 - Never move text blocks or even complete files around in the document tree with corrupting links all over the document tree
 - Use terms all over the document tree, which are automatically linked to their explanation.
+- Provide examples documentation consistent with working code.
 
 ## Command Line Syntax
 
@@ -36,6 +37,17 @@ and usage list is printed.
 
 The source folder may not only contain markdown files. The generator copies all non-markdown files in the same structure to the target folder.
 
+## General Annotation Syntax
+
+Annotations used by this generator use a common syntax
+
+```
+{{<elementsyntax>}}
+```
+
+Elements may be [anchors](doc/chapters/references.md#anchors), [term anchors](doc/chapters/terms.md#anchors), [references](doc/chapters/references.md#references) or [commands](doc/chapters/commands.md#commands).
+
+
 ## Reference and Anchor Syntax
 
 Anchors and references are character sequences
@@ -53,8 +65,8 @@ may be copied or even moved into a completely different folder structure without
 Therefore, the anchors must be globally unique in the
 complete document tree.
 
-The generator supports two kinds of references:
-- [Reference targets](doc/chapters/references.md#reference-targets) 
+The generator supports two kinds of references as well as anchors:
+- [References](doc/chapters/references.md#references) 
 - [Terms](doc/chapters/terms.md#terms)
 
 ## Commands

VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

cmds.go

@@ -10,12 +10,14 @@ import (
 )
 
 type Command interface {
+	Position() string
 	GetSubstitution(path string) ([]byte, error)
 }
 
 type Commands map[string]Command
 
 type Include struct {
+	_Position
 	file string
 }
 
@@ -49,7 +51,7 @@ var includeExpPat = regexp.MustCompile("^{([^}]+)}{([a-zA-Z -]+)}$")
 // --- end include args ---
 // --- end example ---
 
-func NewInclude(args []byte) (Command, error) {
+func NewInclude(line, col int, args []byte) (Command, error) {
 	var err error
 
 	matches := includeExpNum.FindSubmatch(args)
@@ -68,12 +70,12 @@ func NewInclude(args []byte) (Command, error) {
 				return nil, fmt.Errorf("invalid start line: %w", err)
 			}
 		}
-		return &IncludeNum{Include{string(matches[1])}, int(start), int(end)}, nil
+		return &IncludeNum{Include{Position{line, col}, string(matches[1])}, int(start), int(end)}, nil
 	}
 
 	matches = includeExpPat.FindSubmatch(args)
 	if len(matches) != 0 {
-		return &IncludePat{Include{string(matches[1])}, string(matches[2])}, nil
+		return &IncludePat{Include{Position{line, col}, string(matches[1])}, string(matches[2])}, nil
 	}
 
 	return nil, fmt.Errorf("invalid include arguments %q", string(args))

doc/chapters/commands.md

@@ -13,23 +13,25 @@ The following commands are supported:
 
 The include command uses the following syntax
 <pre>
-{{include}{<filepath>}[{[<startline>][:[<endline>]]}]}
-{{include}{<filepath>}{<key>}&rcub;
+{{include}{&lt;filepath>}[{[&lt;startline>][:[&lt;endline>]]}]}
+{{include}{&lt;filepath>}{<key>}&rcub;
 </pre>
 
-In the first flavor numberimg starts from 1, given start and end line are included.
-If omitted the selection starts from the beginng or is taken to the end.
 
-In the second flavotr the content between two lines containing the pattern
+In the first flavor numbering starts from 1, given start and end line are included.
+If omitted the selection starts from the beginning or is taken to the end.
+
+In the second flavor the content between two lines containing the pattern
 `--- begin <key> ---` and `--- end <key> ---` is used.
-Those pattern MUST occur exactly once.
+Those patterns MUST occur exactly once.
 
-This way it is possible to include some
-content from another file, for example
-a Go file like in the following example
+This command can be used to embed some content of another file into the 
+Markdown file, for example
+parts of a Go file to provide some documentation consistent with actual
+code like in the following example
 
 <pre>
-{{include}{../../../scan.go}{90:93}&rcub;
+{{include}{../../../scan.go}{102:105}&rcub;
 </pre>
 
 which extracts the regular expressions used
@@ -42,6 +44,9 @@ var tgtExp = regexp.MustCompile(`[^([]{{([a-z][a-z0-9.-]*)(:([a-zA-Z][a-zA-Z0-9-
 var cmdExp = regexp.MustCompile(`{{([a-z]+)}((?:{[^}]+})+)}`)
 ```
 
+The second example uses the pattern syntax
+to determine include content:
+
 <pre>
 {{include}{../../../cmds.go}{include args}&rcub;
 </pre>

doc/chapters/references.md

@@ -1,8 +1,8 @@
 
-## Reference Targets
+## References
 
 Any reference in a Markdown document may
-use the annotated reference syntax to refer to global logical anchors.
+use the annotated reference syntax to refer to a global logical anchors.
 
 
 <pre>
@@ -31,4 +31,10 @@ For example
 </pre>
 
 It might be placed anywhere in a markdown document,
-therefore, it is possible to link to any location, not only section headers.
+therefore, it is possible to link to any location, not only section headers.
+
+If placed directly before or after a Markdown section heading
+(and the option `--headings`) is given, no explicit anchor is generated,
+but the Markdown anchor name is used for the references.
+This keeps the generated file viewable by Markdown viewers not able to
+work with anchors. 

doc/chapters/terms.md

@@ -3,7 +3,8 @@
 
 Instead of using a reference as target for a markdown
 reference it may be used as complete markdown linked text.
-In this case the [logical reference](references.md#reference-targets) appears inside the `[]` pair of a markdown reference, but without the target part:
+In this case the [logical reference](references.md#references) appears inside the `[]` pair
+of a markdown reference, but without the target part:
 
 <pre>
 A [{{&lt;name>}}] is a ....
@@ -22,7 +23,8 @@ There are several flavors for using a term:
 
 ### Anchors
 
-Anchors for terms are just defined by using the reference syntax outside the markdown reference syntax and adding a text separated by a colon ( `:`).
+Anchors for terms are just defined by using the reference syntax outside the
+Markdown reference syntax and adding a text separated by a colon ( `:`).
 
 For example
 
@@ -32,4 +34,6 @@ For example
 </pre>
 
 It might be placed anywhere in a Markdown document,
-therefore, it is possible to link to any location, not only section headers.
+therefore, it is possible to link to any location, not only section headers.
+
+Term anchors may be used for regular references, also.

generate.go

@@ -79,7 +79,7 @@ func generate(files []*File, resolution Resolution, source, target string) error
 				exp := regexp.MustCompile(regexp.QuoteMeta(k))
 				sub, err := c.GetSubstitution(src)
 				if err != nil {
-					return fmt.Errorf("%s: %s; %w", f.relpath, k, err)
+					return fmt.Errorf("%s: %s: %s; %w", f.relpath, c.Position(), k, err)
 				}
 				data = exp.ReplaceAll(data, sub)
 			}

go.sum

@@ -2,5 +2,35 @@ github.com/Masterminds/semver/v3 v3.2.1 h1:RN9w6+7QoMeJVGyfmbcgs28Br8cvmnucEXnY0
 github.com/Masterminds/semver/v3 v3.2.1/go.mod h1:qvl/7zhW3nngYb5+80sSMF+FG2BjYrf8m9wsX0PNOMQ=
 github.com/gertd/go-pluralize v0.2.1 h1:M3uASbVjMnTsPb0PNqg+E/24Vwigyo/tvyMTtAlLgiA=
 github.com/gertd/go-pluralize v0.2.1/go.mod h1:rbYaKDbsXxmRfr8uygAEKhOWsjyrrqrkHVpZvoOp8zk=
+github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
+golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
+golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
+golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
+golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
+golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
 golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
+golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=

mdref.go

@@ -4,8 +4,6 @@ import (
 	"fmt"
 	"os"
 	"strings"
-
-	"github.com/mandelsoft/mdref/version"
 )
 
 type Resolution map[string]*File
@@ -33,7 +31,7 @@ func main() {
 	args := os.Args[1:]
 	for len(args) > 0 && strings.HasPrefix(args[0], "--") {
 		if args[0] == "--version" {
-			info := version.Get()
+			info := Get()
 
 			fmt.Printf("mdgen version %s.%s.%s (%s) [%s %s]\n", info.Major, info.Minor, info.Patch, info.PreRelease, info.GitTreeState, info.GitCommit)
 			os.Exit(0)
@@ -91,6 +89,7 @@ printed, additionally.
 
 	resolution, err := resolve(files)
 	Error(err)
+	Error(checkCommands(src, files))
 
 	if opts.Print {
 		Print(files, resolution)