diff options
author | Ingo Schwarze <schwarze@openbsd.org> | 2020-03-13 15:32:28 +0000 |
---|---|---|
committer | Ingo Schwarze <schwarze@openbsd.org> | 2020-03-13 15:32:28 +0000 |
commit | f10f0fe3970de778125a29d73e65e63f32c138e1 (patch) | |
tree | 757b21a5fff7cfdab542f40f9aa0e1306287415c /mandoc_headers.3 | |
parent | 62450180320c529d836c4c25672879a7ce53221a (diff) | |
download | mandoc-f10f0fe3970de778125a29d73e65e63f32c138e1.tar.gz mandoc-f10f0fe3970de778125a29d73e65e63f32c138e1.tar.zst mandoc-f10f0fe3970de778125a29d73e65e63f32c138e1.zip |
Split tagging into a validation part including prioritization
in tag.{h,c} and {mdoc,man}_validate.c
and into a formatting part including command line argument checking
in term_tag.{h,c}, html.c, and {mdoc|man}_{term|html}.c.
Immediate functional benefits include:
* Improved prioritization of automatic tags for .Em and .Sy.
* Avoiding bogus automatic tags when .Em, .Fn, or .Sy are explicitly tagged.
* Explicit tagging of .Er and .Fl now works in HTML output.
* Automatic tagging of .IP and .TP now works in HTML output.
But mainly, this patch provides clean earth to build further improvements on.
Technical changes:
* Main program: Write a tag file for ASCII and UTF-8 output only.
* All formatters: There is no more need to delay writing the tags.
* mdoc(7)+man(7) formatters: No more need for elaborate syntax tree inspection.
* HTML formatter: If available, use the "string" attribute as the tag.
* HTML formatter: New function to write permalinks, to reduce code duplication.
Style cleanup in the vicinity while here:
* mdoc(7) terminal formatter: To set up bold font for children,
defer to termp_bold_pre() rather than calling term_fontpush() manually.
* mdoc(7) terminal formatter: Garbage collect some duplicate functions.
* mdoc(7) HTML formatter: Unify <code> handling, delete redundant functions.
* Where possible, use switch statements rather than if cascades.
* Get rid of some more Yoda notation.
The necessity for such changes was first discussed with kn@, but i didn't
bother him with a request to review the resulting -673/+782 line patch.
Diffstat (limited to 'mandoc_headers.3')
-rw-r--r-- | mandoc_headers.3 | 77 |
1 files changed, 57 insertions, 20 deletions
diff --git a/mandoc_headers.3 b/mandoc_headers.3 index 1632b07c..36a8a58d 100644 --- a/mandoc_headers.3 +++ b/mandoc_headers.3 @@ -1,6 +1,6 @@ -.\" $Id: mandoc_headers.3,v 1.32 2020/01/20 10:37:15 schwarze Exp $ +.\" $Id: mandoc_headers.3,v 1.33 2020/03/13 15:32:28 schwarze Exp $ .\" -.\" Copyright (c) 2014-2019 Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright (c) 2014-2020 Ingo Schwarze <schwarze@openbsd.org> .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: January 20 2020 $ +.Dd $Mdocdate: March 13 2020 $ .Dt MANDOC_HEADERS 3 .Os .Sh NAME @@ -232,6 +232,30 @@ and the functions .Fn mandoc_xr_get , and .Fn mandoc_xr_free . +.It Qq Pa tag.h +Internal interfaces to tag syntax tree nodes, +for use by validation modules only. +.Pp +Requires +.In limits.h +for +.Dv INT_MAX . +.Pp +Provides the functions +.Fn tag_alloc , +.Fn tag_put , +.Fn tag_check , +and +.Fn tag_free +and some +.Dv TAG_* +constants. +.Pp +Uses the type +.Vt struct roff_node +from +.Qq Pa roff.h +as an opaque type for function prototypes. .El .Pp The following two require @@ -587,6 +611,33 @@ When this header is included, the same file should not include .Qq Pa html.h or .Qq Pa mansearch.h . +.It Qq Pa tag_term.h +Requires +.In sys/types.h +for +.Vt size_t +and +.In stdio.h +for +.Vt FILE . +.Pp +Provides an interface to generate +.Xr ctags 1 +files for the +.Ic :t +functionality mentioned in +.Xr man 1 . +.Pp +Uses the type +.Vt struct roff_node +from +.Qq Pa roff.h +as an opaque type for function prototypes. +.Pp +When this header is included, the same file should not include +.Qq Pa html.h +or +.Qq Pa mansearch.h . .It Qq Pa html.h Requires .In sys/types.h @@ -629,25 +680,10 @@ from as opaque types for function prototypes. .Pp When this header is included, the same file should not include -.Qq Pa term.h +.Qq Pa term.h , +.Qq Pa tab_term.h , or .Qq Pa mansearch.h . -.It Qq Pa tag.h -Requires -.In sys/types.h -for -.Vt size_t -and -.In limits.h -for -.Dv INT_MAX . -.Pp -Provides an interface to generate -.Xr ctags 1 -files for the -.Ic :t -functionality mentioned in -.Xr man 1 . .It Qq Pa main.h Provides the top level steering functions for all formatters. .Pp @@ -700,6 +736,7 @@ as an opaque type for function prototypes. When this header is included, the same file should not include .Qq Pa out.h , .Qq Pa term.h , +.Qq Pa tab_term.h , or .Qq Pa html.h . .El |