* mandoc: Introduce a new mdoc(7) macro .Tg ("tag") to explicitly mark a
@ 2020-01-19 18:02 schwarze
0 siblings, 0 replies; only message in thread
From: schwarze @ 2020-01-19 18:02 UTC (permalink / raw)
To: source
Log Message:
-----------
Introduce a new mdoc(7) macro .Tg ("tag") to explicitly mark a place
as defining a term. Please only use it when automatic tagging does
not work. Manual page authors will not be required to add the new
macro; using it remains optional. HTML output is still rudimentary
in this version and will be polished later.
Thanks to kn@ for reminding me that i have been considering since
BSDCan 2014 whether something like this might be useful. Given
that possibilities of making automatic tagging better are running
out and there are still several situations where automatic tagging
cannot do the job, i think the time is now ripe.
Feedback and no objection from millert@; OK espie@ inoguchi@ kn@.
Modified Files:
--------------
mandoc:
html.c
html.h
mandoc.h
mandoc_msg.c
mdoc.7
mdoc_html.c
mdoc_macro.c
mdoc_man.c
mdoc_markdown.c
mdoc_state.c
mdoc_term.c
mdoc_validate.c
roff.c
roff.h
tag.c
Revision Data
-------------
Index: html.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/html.c,v
retrieving revision 1.261
retrieving revision 1.262
diff -Lhtml.c -Lhtml.c -u -p -r1.261 -r1.262
--- html.c
+++ html.c
@@ -88,6 +88,7 @@ static const struct htmldata htmltags[TA
{"span", HTML_INPHRASE | HTML_TOPHRASE},
{"var", HTML_INPHRASE | HTML_TOPHRASE},
{"br", HTML_INPHRASE | HTML_NOSTACK | HTML_NLALL},
+ {"mark", HTML_INPHRASE | HTML_NOSTACK },
{"math", HTML_INPHRASE | HTML_NLALL | HTML_INDENT},
{"mrow", 0},
{"mi", 0},
Index: mdoc_term.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc_term.c,v
retrieving revision 1.374
retrieving revision 1.375
diff -Lmdoc_term.c -Lmdoc_term.c -u -p -r1.374 -r1.375
--- mdoc_term.c
+++ mdoc_term.c
@@ -1,7 +1,7 @@
/* $Id$ */
/*
* Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2010, 2012-2019 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2010, 2012-2020 Ingo Schwarze <schwarze@openbsd.org>
* Copyright (c) 2013 Franco Fichtner <franco@lastsummer.de>
*
* Permission to use, copy, modify, and distribute this software for any
@@ -119,6 +119,7 @@ static int termp_pp_pre(DECL_ARGS);
static int termp_ss_pre(DECL_ARGS);
static int termp_sy_pre(DECL_ARGS);
static int termp_tag_pre(DECL_ARGS);
+static int termp_tg_pre(DECL_ARGS);
static int termp_under_pre(DECL_ARGS);
static int termp_vt_pre(DECL_ARGS);
static int termp_xr_pre(DECL_ARGS);
@@ -245,6 +246,7 @@ static const struct mdoc_term_act mdoc_t
{ NULL, termp____post }, /* %Q */
{ NULL, termp____post }, /* %U */
{ NULL, NULL }, /* Ta */
+ { termp_tg_pre, NULL }, /* Tg */
};
static int fn_prio;
@@ -2079,6 +2081,13 @@ termp_tag_pre(DECL_ARGS)
n->parent->parent->parent->tok == MDOC_It)))
tag_put(n->child->string, 1, p->line);
return 1;
+}
+
+static int
+termp_tg_pre(DECL_ARGS)
+{
+ tag_put(n->child->string, -2, p->line);
+ return 0;
}
static int
Index: mdoc_man.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc_man.c,v
retrieving revision 1.132
retrieving revision 1.133
diff -Lmdoc_man.c -Lmdoc_man.c -u -p -r1.132 -r1.133
--- mdoc_man.c
+++ mdoc_man.c
@@ -262,6 +262,7 @@ static const struct mdoc_man_act mdoc_ma
{ NULL, NULL, post_percent, NULL, NULL }, /* %Q */
{ NULL, NULL, post_percent, NULL, NULL }, /* %U */
{ NULL, NULL, NULL, NULL, NULL }, /* Ta */
+ { NULL, NULL, NULL, NULL, NULL }, /* Tg */
};
static const struct mdoc_man_act *mdoc_man_act(enum roff_tok);
Index: mdoc_markdown.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc_markdown.c,v
retrieving revision 1.31
retrieving revision 1.32
diff -Lmdoc_markdown.c -Lmdoc_markdown.c -u -p -r1.31 -r1.32
--- mdoc_markdown.c
+++ mdoc_markdown.c
@@ -226,6 +226,7 @@ static const struct md_act md_acts[MDOC_
{ NULL, NULL, md_post_pc, NULL, NULL }, /* %Q */
{ NULL, md_pre_Lk, md_post_pc, NULL, NULL }, /* %U */
{ NULL, NULL, NULL, NULL, NULL }, /* Ta */
+ { NULL, NULL, NULL, NULL, NULL }, /* Tg */
};
static const struct md_act *md_act(enum roff_tok);
Index: mdoc_macro.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc_macro.c,v
retrieving revision 1.233
retrieving revision 1.234
diff -Lmdoc_macro.c -Lmdoc_macro.c -u -p -r1.233 -r1.234
--- mdoc_macro.c
+++ mdoc_macro.c
@@ -1,7 +1,7 @@
/* $Id$ */
/*
* Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2010, 2012-2019 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2010, 2012-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
@@ -200,6 +200,7 @@ static const struct mdoc_macro mdoc_macr
{ in_line_eoln, MDOC_JOIN }, /* %Q */
{ in_line_eoln, 0 }, /* %U */
{ phrase_ta, MDOC_CALLABLE | MDOC_PARSED | MDOC_JOIN }, /* Ta */
+ { in_line_eoln, 0 }, /* Tg */
};
Index: roff.h
===================================================================
RCS file: /home/cvs/mandoc/mandoc/roff.h,v
retrieving revision 1.69
retrieving revision 1.70
diff -Lroff.h -Lroff.h -u -p -r1.69 -r1.70
--- roff.h
+++ roff.h
@@ -1,7 +1,7 @@
/* $Id$ */
/*
* Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2013-2015, 2017-2019 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2013-2015, 2017-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
@@ -437,6 +437,7 @@ enum roff_tok {
MDOC__Q,
MDOC__U,
MDOC_Ta,
+ MDOC_Tg,
MDOC_MAX,
MAN_TH,
MAN_SH,
Index: mdoc_validate.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc_validate.c,v
retrieving revision 1.376
retrieving revision 1.377
diff -Lmdoc_validate.c -Lmdoc_validate.c -u -p -r1.376 -r1.377
--- mdoc_validate.c
+++ mdoc_validate.c
@@ -113,6 +113,7 @@ static void post_sm(POST_ARGS);
static void post_st(POST_ARGS);
static void post_std(POST_ARGS);
static void post_sx(POST_ARGS);
+static void post_tg(POST_ARGS);
static void post_useless(POST_ARGS);
static void post_xr(POST_ARGS);
static void post_xx(POST_ARGS);
@@ -238,6 +239,7 @@ static const v_post mdoc_valids[MDOC_MAX
NULL, /* %Q */
NULL, /* %U */
NULL, /* Ta */
+ post_tg, /* Tg */
};
#define RSORD_MAX 14 /* Number of `Rs' blocks. */
@@ -1090,6 +1092,41 @@ post_st(POST_ARGS)
}
static void
+post_tg(POST_ARGS)
+{
+ struct roff_node *n, *nch;
+ size_t len;
+
+ n = mdoc->last;
+ nch = n->child;
+ if (nch == NULL && n->next != NULL &&
+ n->next->child->type == ROFFT_TEXT) {
+ mdoc->next = ROFF_NEXT_CHILD;
+ roff_word_alloc(mdoc, n->line, n->pos, n->next->child->string);
+ nch = mdoc->last;
+ nch->flags |= NODE_NOSRC;
+ mdoc->last = n;
+ }
+ if (nch == NULL || *nch->string == '\0') {
+ mandoc_msg(MANDOCERR_MACRO_EMPTY, n->line, n->pos, "Tg");
+ roff_node_delete(mdoc, n);
+ return;
+ }
+ len = strcspn(nch->string, " \t");
+ if (nch->string[len] != '\0')
+ mandoc_msg(MANDOCERR_TG_SPC, nch->line, nch->pos + len + 1,
+ "Tg %s", nch->string);
+ if (nch->next != NULL) {
+ mandoc_msg(MANDOCERR_ARG_EXCESS, nch->next->line,
+ nch->next->pos, "Tg ... %s", nch->next->string);
+ while (nch->next != NULL)
+ roff_node_delete(mdoc, nch->next);
+ }
+ if (nch->string[len] != '\0')
+ roff_node_delete(mdoc, n);
+}
+
+static void
post_obsolete(POST_ARGS)
{
struct roff_node *n;
@@ -1754,7 +1791,7 @@ post_bl(POST_ARGS)
while (nchild != NULL) {
nnext = nchild->next;
if (nchild->tok == MDOC_It ||
- (nchild->tok == MDOC_Sm &&
+ ((nchild->tok == MDOC_Sm || nchild->tok == MDOC_Tg) &&
nnext != NULL && nnext->tok == MDOC_It)) {
nchild = nnext;
continue;
Index: mandoc_msg.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mandoc_msg.c,v
retrieving revision 1.9
retrieving revision 1.10
diff -Lmandoc_msg.c -Lmandoc_msg.c -u -p -r1.9 -r1.10
--- mandoc_msg.c
+++ mandoc_msg.c
@@ -223,6 +223,7 @@ static const char *const type_message[MA
"excessive shift",
"NOT IMPLEMENTED: .so with absolute path or \"..\"",
".so request failed",
+ "skipping tag containing whitespace",
"skipping all arguments",
"skipping excess arguments",
"divide by zero",
Index: mdoc_html.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc_html.c,v
retrieving revision 1.332
retrieving revision 1.333
diff -Lmdoc_html.c -Lmdoc_html.c -u -p -r1.332 -r1.333
--- mdoc_html.c
+++ mdoc_html.c
@@ -1,7 +1,7 @@
/* $Id$ */
/*
* Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
- * 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
@@ -115,6 +115,7 @@ static int mdoc_ss_pre(MDOC_ARGS);
static int mdoc_st_pre(MDOC_ARGS);
static int mdoc_sx_pre(MDOC_ARGS);
static int mdoc_sy_pre(MDOC_ARGS);
+static int mdoc_tg_pre(MDOC_ARGS);
static int mdoc_va_pre(MDOC_ARGS);
static int mdoc_vt_pre(MDOC_ARGS);
static int mdoc_xr_pre(MDOC_ARGS);
@@ -241,6 +242,7 @@ static const struct mdoc_html_act mdoc_h
{mdoc__x_pre, mdoc__x_post}, /* %Q */
{mdoc__x_pre, mdoc__x_post}, /* %U */
{NULL, NULL}, /* Ta */
+ {mdoc_tg_pre, NULL}, /* Tg */
};
@@ -718,6 +720,16 @@ mdoc_xr_pre(MDOC_ARGS)
print_text(h, n->string);
h->flags |= HTML_NOSPACE;
print_text(h, ")");
+ return 0;
+}
+
+static int
+mdoc_tg_pre(MDOC_ARGS)
+{
+ char *id;
+
+ if ((id = html_make_id(n, 1)) != NULL)
+ print_otag(h, TAG_MARK, "i", id);
return 0;
}
Index: mandoc.h
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mandoc.h,v
retrieving revision 1.265
retrieving revision 1.266
diff -Lmandoc.h -Lmandoc.h -u -p -r1.265 -r1.266
--- mandoc.h
+++ mandoc.h
@@ -223,6 +223,7 @@ enum mandocerr {
MANDOCERR_SHIFT, /* excessive shift: ..., but max is ... */
MANDOCERR_SO_PATH, /* NOT IMPLEMENTED: .so with absolute path or ".." */
MANDOCERR_SO_FAIL, /* .so request failed */
+ MANDOCERR_TG_SPC, /* skipping tag containing whitespace: tag */
MANDOCERR_ARG_SKIP, /* skipping all arguments: macro args */
MANDOCERR_ARG_EXCESS, /* skipping excess arguments: macro ... args */
MANDOCERR_DIVZERO, /* divide by zero */
Index: html.h
===================================================================
RCS file: /home/cvs/mandoc/mandoc/html.h,v
retrieving revision 1.105
retrieving revision 1.106
diff -Lhtml.h -Lhtml.h -u -p -r1.105 -r1.106
--- html.h
+++ html.h
@@ -48,6 +48,7 @@ enum htmltag {
TAG_SPAN,
TAG_VAR,
TAG_BR,
+ TAG_MARK,
TAG_MATH,
TAG_MROW,
TAG_MI,
Index: tag.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/tag.c,v
retrieving revision 1.25
retrieving revision 1.26
diff -Ltag.c -Ltag.c -u -p -r1.25 -r1.26
--- tag.c
+++ tag.c
@@ -1,6 +1,6 @@
/* $Id$ */
/*
- * Copyright (c) 2015, 2016, 2018, 2019 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2015,2016,2018,2019,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
@@ -196,12 +196,13 @@ tag_put(const char *s, int prio, size_t
/* A better entry is already present, ignore the new one. */
- if (entry->prio > 0 && entry->prio < prio)
+ if (entry->prio != -1 && entry->prio < prio)
return;
/* The existing entry is worse, clear it. */
- if (entry->prio < 1 || entry->prio > prio)
+ if (entry->prio == -1 || entry->prio == 0 ||
+ entry->prio > prio)
entry->nlines = 0;
}
@@ -241,7 +242,7 @@ tag_write(void)
empty = 1;
entry = ohash_first(&tag_data, &slot);
while (entry != NULL) {
- if (stream != NULL && entry->prio >= 0) {
+ if (stream != NULL && entry->prio != -1) {
for (i = 0; i < entry->nlines; i++) {
fprintf(stream, "%s %s %zu\n",
entry->s, tag_files.ofn, entry->lines[i]);
Index: mdoc.7
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc.7,v
retrieving revision 1.279
retrieving revision 1.280
diff -Lmdoc.7 -Lmdoc.7 -u -p -r1.279 -r1.280
--- mdoc.7
+++ mdoc.7
@@ -1,7 +1,7 @@
.\" $Id$
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2010, 2011, 2013-2018 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010, 2011, 2013-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
@@ -449,6 +449,7 @@ in the alphabetical
.It Ic \&Ss Ta subsection header (one line)
.It Ic \&Sx Ta internal cross reference to a section or subsection
.It Ic \&Xr Ta cross reference to another manual page: Ar name section
+.It Ic \&Tg Ta tag the definition of a Ar term Pq <= 1 arguments
.It Ic \&Pp Ta start a text paragraph (no arguments)
.El
.Ss Displays and lists
@@ -2548,6 +2549,49 @@ Table cell separator in
.Ic \&Bl Fl column
lists; can only be used below
.Ic \&It .
+.It Ic \&Tg Op Ar term
+Announce that the next input line starts a definition of the
+.Ar term .
+This macro must appear alone on its own input line.
+The argument defaults to the first argument of the first macro
+on the next line.
+The argument may not contain whitespace characters, not even when it is quoted.
+This macro is a
+.Xr mandoc 1
+extension and is typically ignored by other formatters.
+.Pp
+When viewing terminal output with
+.Xr less 1 ,
+the interactive
+.Ic :t
+command can be used to go to the definition of the
+.Ar term
+as described for the
+.Ev MANPAGER
+variable in
+.Xr man 1 ;
+when producing HTML output, a fragment identifier
+.Pq Ic id No attribute
+is generated, to be used for deep linking to this place of the document.
+.Pp
+In most cases, adding a
+.Ic \&Tg
+macro would be redundant because
+.Xr mandoc 1
+is able to automatically tag most definitions.
+This macro is intended for cases where automatic tagging of a
+.Ar term
+is unsatisfactory, for example if a definition is not tagged
+automatically (false negative) or if places are tagged that do
+not define the
+.Ar term
+(false positives).
+When there is at least one
+.Ic \&Tg
+macro for a
+.Ar term ,
+no other places are automatically marked as definitions of that
+.Ar term .
.It Ic \&Tn Ar word ...
Supported only for compatibility, do not use this in new manuals.
Even though the macro name
@@ -2912,6 +2956,7 @@ then the macro accepts an arbitrary numb
.It Ic \&St Ta \&No Ta Yes Ta 1
.It Ic \&Sx Ta Yes Ta Yes Ta >0
.It Ic \&Sy Ta Yes Ta Yes Ta >0
+.It Ic \&Tg Ta \&No Ta \&No Ta <2
.It Ic \&Tn Ta Yes Ta Yes Ta >0
.It Ic \&Ud Ta \&No Ta \&No Ta 0
.It Ic \&Ux Ta Yes Ta Yes Ta n
Index: mdoc_state.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc_state.c,v
retrieving revision 1.15
retrieving revision 1.16
diff -Lmdoc_state.c -Lmdoc_state.c -u -p -r1.15 -r1.16
--- mdoc_state.c
+++ mdoc_state.c
@@ -157,6 +157,7 @@ static const state_handler state_handler
NULL, /* %Q */
NULL, /* %U */
NULL, /* Ta */
+ NULL, /* Tg */
};
Index: roff.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/roff.c,v
retrieving revision 1.368
retrieving revision 1.369
diff -Lroff.c -Lroff.c -u -p -r1.368 -r1.369
--- roff.c
+++ roff.c
@@ -1,7 +1,7 @@
/* $Id$ */
/*
* Copyright (c) 2008-2012, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2010-2015, 2017-2019 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2010-2015, 2017-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
@@ -355,7 +355,7 @@ const char *__roff_name[MAN_MAX + 1] = {
"Lk", "Mt", "Brq", "Bro",
"Brc", "%C", "Es", "En",
"Dx", "%Q", "%U", "Ta",
- NULL,
+ "Tg", NULL,
"TH", "SH", "SS", "TP",
"TQ",
"LP", "PP", "P", "IP",
--
To unsubscribe send an email to source+unsubscribe@mandoc.bsd.lv
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2020-01-19 18:02 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-01-19 18:02 mandoc: Introduce a new mdoc(7) macro .Tg ("tag") to explicitly mark a schwarze
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).