* clean up date handling
@ 2011-03-04 0:14 Ingo Schwarze
2011-03-04 22:24 ` Ingo Schwarze
0 siblings, 1 reply; 5+ messages in thread
From: Ingo Schwarze @ 2011-03-04 0:14 UTC (permalink / raw)
To: tech; +Cc: Tim van der Molen
Hi,
Tim recently noticed inconsistencies between mandoc date handling
and what the manuals say about it. Having a closer look, i came
to the conclusion that this is one of the rare fields where
compatibility with new groff really makes no sense because groff
makes too many bad decisions. Besides, it is well-known that
this area is one of the worst sources of warnings, and i feel
these warnings are not really useful.
So, here is a radical cleanup of date handling (-99 +69).
Basically, it store all dates as strings everywhere, which simplifies
handling a lot, in particular in the frontends, and it tries the three
most common formats everywhere; in case of mismatch it just copies the
date string verbatim, or if there is no string at all, it uses the
current date.
This needs more testing, but i won't continue on it tonight, so i'm
showing it around for comments.
Note that i removed all warnings. Maybe that's ok.
Maybe we should sparingly restore a few.
I'm going to reconsider that aspect.
I'm planning to look at the manuals once we agree about the
functionality we want.
Yours,
Ingo
Index: libmandoc.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/libmandoc.h,v
retrieving revision 1.8
diff -u -p -r1.8 libmandoc.h
--- libmandoc.h 3 Jan 2011 22:27:21 -0000 1.8
+++ libmandoc.h 3 Mar 2011 23:56:33 -0000
@@ -25,11 +25,7 @@ char *mandoc_strdup(const char *);
void *mandoc_malloc(size_t);
void *mandoc_realloc(void *, size_t);
char *mandoc_getarg(char **, mandocmsg, void *, int, int *);
-time_t mandoc_a2time(int, const char *);
-#define MTIME_CANONICAL (1 << 0)
-#define MTIME_REDUCED (1 << 1)
-#define MTIME_MDOCDATE (1 << 2)
-#define MTIME_ISO_8601 (1 << 3)
+char *mandoc_normdate(char *);
int mandoc_eos(const char *, size_t, int);
int mandoc_hyph(const char *, const char *);
Index: main.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/main.c,v
retrieving revision 1.72
diff -u -p -r1.72 main.c
--- main.c 6 Feb 2011 17:33:20 -0000 1.72
+++ main.c 3 Mar 2011 23:56:33 -0000
@@ -113,7 +113,6 @@ static const char * const mandocerrs[MAN
"no title in document",
"document title should be all caps",
"unknown manual section",
- "cannot parse date argument",
"prologue macros out of order",
"duplicate prologue macro",
"macro not allowed in prologue",
Index: man.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/man.c,v
retrieving revision 1.55
diff -u -p -r1.55 man.c
--- man.c 10 Feb 2011 00:06:30 -0000 1.55
+++ man.c 3 Mar 2011 23:56:33 -0000
@@ -142,8 +142,8 @@ man_free1(struct man *man)
free(man->meta.title);
if (man->meta.source)
free(man->meta.source);
- if (man->meta.rawdate)
- free(man->meta.rawdate);
+ if (man->meta.date)
+ free(man->meta.date);
if (man->meta.vol)
free(man->meta.vol);
if (man->meta.msec)
Index: man.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/man.h,v
retrieving revision 1.34
diff -u -p -r1.34 man.h
--- man.h 16 Jan 2011 02:56:47 -0000 1.34
+++ man.h 3 Mar 2011 23:56:33 -0000
@@ -75,8 +75,7 @@ enum man_type {
*/
struct man_meta {
char *msec; /* `TH' section (1, 3p, etc.) */
- time_t date; /* `TH' normalised date */
- char *rawdate; /* raw `TH' date */
+ char *date; /* `TH' normalised date */
char *vol; /* `TH' volume */
char *title; /* `TH' title (e.g., FOO) */
char *source; /* `TH' source (e.g., GNU) */
Index: man_html.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/man_html.c,v
retrieving revision 1.34
diff -u -p -r1.34 man_html.c
--- man_html.c 17 Jan 2011 00:15:19 -0000 1.34
+++ man_html.c 3 Mar 2011 23:56:34 -0000
@@ -330,12 +330,6 @@ man_root_post(MAN_ARGS)
{
struct htmlpair tag[3];
struct tag *t, *tt;
- char b[DATESIZ];
-
- if (m->rawdate)
- strlcpy(b, m->rawdate, DATESIZ);
- else
- time2a(m->date, b, DATESIZ);
PAIR_SUMMARY_INIT(&tag[0], "Document Footer");
PAIR_CLASS_INIT(&tag[1], "foot");
@@ -353,7 +347,7 @@ man_root_post(MAN_ARGS)
PAIR_CLASS_INIT(&tag[0], "foot-date");
print_otag(h, TAG_TD, 1, tag);
- print_text(h, b);
+ print_text(h, m->date);
print_stagq(h, tt);
PAIR_CLASS_INIT(&tag[0], "foot-os");
Index: man_term.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/man_term.c,v
retrieving revision 1.64
diff -u -p -r1.64 man_term.c
--- man_term.c 25 Jan 2011 12:35:07 -0000 1.64
+++ man_term.c 3 Mar 2011 23:56:34 -0000
@@ -939,24 +939,18 @@ print_man_nodelist(DECL_ARGS)
static void
print_man_foot(struct termp *p, const void *arg)
{
- char buf[DATESIZ];
const struct man_meta *meta;
meta = (const struct man_meta *)arg;
term_fontrepl(p, TERMFONT_NONE);
- if (meta->rawdate)
- strlcpy(buf, meta->rawdate, DATESIZ);
- else
- time2a(meta->date, buf, DATESIZ);
-
term_vspace(p);
term_vspace(p);
term_vspace(p);
p->flags |= TERMP_NOSPACE | TERMP_NOBREAK;
- p->rmargin = p->maxrmargin - term_strlen(p, buf);
+ p->rmargin = p->maxrmargin - term_strlen(p, meta->date);
p->offset = 0;
/* term_strlen() can return zero. */
@@ -974,7 +968,7 @@ print_man_foot(struct termp *p, const vo
p->rmargin = p->maxrmargin;
p->flags &= ~TERMP_NOBREAK;
- term_word(p, buf);
+ term_word(p, meta->date);
term_flushln(p);
}
Index: man_validate.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/man_validate.c,v
retrieving revision 1.40
diff -u -p -r1.40 man_validate.c
--- man_validate.c 17 Jan 2011 00:15:19 -0000 1.40
+++ man_validate.c 3 Mar 2011 23:56:34 -0000
@@ -187,7 +187,7 @@ check_root(CHKARGS)
*/
m->meta.title = mandoc_strdup("unknown");
- m->meta.date = time(NULL);
+ m->meta.date = mandoc_normdate(NULL);
m->meta.msec = mandoc_strdup("1");
}
@@ -379,12 +379,11 @@ post_TH(CHKARGS)
free(m->meta.source);
if (m->meta.msec)
free(m->meta.msec);
- if (m->meta.rawdate)
- free(m->meta.rawdate);
+ if (m->meta.date)
+ free(m->meta.date);
- m->meta.title = m->meta.vol = m->meta.rawdate =
+ m->meta.title = m->meta.vol = m->meta.date =
m->meta.msec = m->meta.source = NULL;
- m->meta.date = 0;
/* ->TITLE<- MSEC DATE SOURCE VOL */
@@ -412,24 +411,9 @@ post_TH(CHKARGS)
/* TITLE MSEC ->DATE<- SOURCE VOL */
- /*
- * Try to parse the date. If this works, stash the epoch (this
- * is optimal because we can reformat it in the canonical form).
- * If it doesn't parse, isn't specified at all, or is an empty
- * string, then use the current date.
- */
-
if (n)
n = n->next;
- if (n && n->string && *n->string) {
- m->meta.date = mandoc_a2time
- (MTIME_ISO_8601, n->string);
- if (0 == m->meta.date) {
- man_nmsg(m, n, MANDOCERR_BADDATE);
- m->meta.rawdate = mandoc_strdup(n->string);
- }
- } else
- m->meta.date = time(NULL);
+ m->meta.date = mandoc_normdate(n ? n->string : NULL);
/* TITLE MSEC DATE ->SOURCE<- VOL */
Index: mandoc.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.c,v
retrieving revision 1.21
diff -u -p -r1.21 mandoc.c
--- mandoc.c 3 Jan 2011 22:27:21 -0000 1.21
+++ mandoc.c 3 Mar 2011 23:56:34 -0000
@@ -27,8 +27,10 @@
#include "mandoc.h"
#include "libmandoc.h"
-static int a2time(time_t *, const char *, const char *);
+#define DATESIZE 32
+static int a2time(time_t *, const char *, const char *);
+static char *time2a(time_t);
int
mandoc_special(char *p)
@@ -376,38 +378,53 @@ a2time(time_t *t, const char *fmt, const
}
-/*
- * Convert from a manual date string (see mdoc(7) and man(7)) into a
- * date according to the stipulated date type.
- */
-time_t
-mandoc_a2time(int flags, const char *p)
+static char *
+time2a(time_t t)
{
- time_t t;
+ struct tm tm;
+ char buf[DATESIZE];
+ char *p;
+ size_t nsz, rsz;
+ int isz;
- if (MTIME_MDOCDATE & flags) {
- if (0 == strcmp(p, "$" "Mdocdate$"))
- return(time(NULL));
- if (a2time(&t, "$" "Mdocdate: %b %d %Y $", p))
- return(t);
- }
+ localtime_r(&t, &tm);
- if (MTIME_CANONICAL & flags || MTIME_REDUCED & flags)
- if (a2time(&t, "%b %d, %Y", p))
- return(t);
-
- if (MTIME_ISO_8601 & flags)
- if (a2time(&t, "%Y-%m-%d", p))
- return(t);
-
- if (MTIME_REDUCED & flags) {
- if (a2time(&t, "%d, %Y", p))
- return(t);
- if (a2time(&t, "%Y", p))
- return(t);
- }
+ p = buf;
+ rsz = DATESIZE;
- return(0);
+ if (0 == (nsz = strftime(p, rsz, "%B ", &tm)))
+ return(NULL);
+
+ p += (int)nsz;
+ rsz -= nsz;
+
+ if (-1 == (isz = snprintf(p, rsz, "%d, ", tm.tm_mday)))
+ return(NULL);
+
+ p += isz;
+ rsz -= isz;
+
+ return(strftime(p, rsz, "%Y", &tm) ? buf : NULL);
+}
+
+
+char *
+mandoc_normdate(char *in)
+{
+ char *out;
+ time_t t;
+
+ if (NULL == in || '\0' == *in ||
+ 0 == strcmp(in, "$" "Mdocdate$"))
+ time(&t);
+
+ else if (!a2time(&t, "$" "Mdocdate: %b %d %Y $", in) &&
+ !a2time(&t, "%b %d, %Y", in) &&
+ !a2time(&t, "%Y-%m-%d", in))
+ t = 0;
+
+ out = t ? time2a(t) : NULL;
+ return(mandoc_strdup(out ? out : in));
}
Index: mandoc.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.h,v
retrieving revision 1.33
diff -u -p -r1.33 mandoc.h
--- mandoc.h 10 Feb 2011 00:06:30 -0000 1.33
+++ mandoc.h 3 Mar 2011 23:56:34 -0000
@@ -50,7 +50,6 @@ enum mandocerr {
MANDOCERR_NOTITLE, /* no title in document */
MANDOCERR_UPPERCASE, /* document title should be all caps */
MANDOCERR_BADMSEC, /* unknown manual section */
- MANDOCERR_BADDATE, /* cannot parse date argument */
MANDOCERR_PROLOGOOO, /* prologue macros out of order */
MANDOCERR_PROLOGREP, /* duplicate prologue macro */
MANDOCERR_BADPROLOG, /* macro not allowed in prologue */
Index: mdoc.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc.c,v
retrieving revision 1.79
diff -u -p -r1.79 mdoc.c
--- mdoc.c 10 Feb 2011 00:06:30 -0000 1.79
+++ mdoc.c 3 Mar 2011 23:56:34 -0000
@@ -314,8 +314,8 @@ mdoc_macro(MACRO_PROT_ARGS)
m->meta.vol = mandoc_strdup("LOCAL");
if (NULL == m->meta.os)
m->meta.os = mandoc_strdup("LOCAL");
- if (0 == m->meta.date)
- m->meta.date = time(NULL);
+ if (NULL == m->meta.date)
+ m->meta.date = mandoc_normdate(NULL);
m->flags |= MDOC_PBODY;
}
Index: mdoc.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc.h,v
retrieving revision 1.43
diff -u -p -r1.43 mdoc.h
--- mdoc.h 30 Jan 2011 17:41:59 -0000 1.43
+++ mdoc.h 3 Mar 2011 23:56:34 -0000
@@ -231,7 +231,7 @@ struct mdoc_meta {
char *msec; /* `Dt' section (1, 3p, etc.) */
char *vol; /* `Dt' volume (implied) */
char *arch; /* `Dt' arch (i386, etc.) */
- time_t date; /* `Dd' normalised date */
+ char *date; /* `Dd' normalised date */
char *title; /* `Dt' title (FOO, etc.) */
char *os; /* `Os' system (OpenBSD, etc.) */
char *name; /* leading `Nm' name */
Index: mdoc_html.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc_html.c,v
retrieving revision 1.52
diff -u -p -r1.52 mdoc_html.c
--- mdoc_html.c 6 Feb 2011 22:56:45 -0000 1.52
+++ mdoc_html.c 3 Mar 2011 23:56:35 -0000
@@ -488,9 +488,6 @@ mdoc_root_post(MDOC_ARGS)
{
struct htmlpair tag[3];
struct tag *t, *tt;
- char b[DATESIZ];
-
- time2a(m->date, b, DATESIZ);
PAIR_SUMMARY_INIT(&tag[0], "Document Footer");
PAIR_CLASS_INIT(&tag[1], "foot");
@@ -510,7 +507,7 @@ mdoc_root_post(MDOC_ARGS)
PAIR_CLASS_INIT(&tag[0], "foot-date");
print_otag(h, TAG_TD, 1, tag);
- print_text(h, b);
+ print_text(h, m->date);
print_stagq(h, tt);
PAIR_CLASS_INIT(&tag[0], "foot-os");
Index: mdoc_term.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc_term.c,v
retrieving revision 1.129
diff -u -p -r1.129 mdoc_term.c
--- mdoc_term.c 6 Feb 2011 22:56:45 -0000 1.129
+++ mdoc_term.c 3 Mar 2011 23:56:35 -0000
@@ -404,7 +404,6 @@ print_mdoc_node(DECL_ARGS)
static void
print_mdoc_foot(struct termp *p, const void *arg)
{
- char buf[DATESIZ], os[BUFSIZ];
const struct mdoc_meta *m;
m = (const struct mdoc_meta *)arg;
@@ -419,24 +418,21 @@ print_mdoc_foot(struct termp *p, const v
* SYSTEM DATE SYSTEM
*/
- time2a(m->date, buf, DATESIZ);
- strlcpy(os, m->os, BUFSIZ);
-
term_vspace(p);
p->offset = 0;
p->rmargin = (p->maxrmargin -
- term_strlen(p, buf) + term_len(p, 1)) / 2;
+ term_strlen(p, m->date) + term_len(p, 1)) / 2;
p->flags |= TERMP_NOSPACE | TERMP_NOBREAK;
- term_word(p, os);
+ term_word(p, m->os);
term_flushln(p);
p->offset = p->rmargin;
- p->rmargin = p->maxrmargin - term_strlen(p, os);
+ p->rmargin = p->maxrmargin - term_strlen(p, m->os);
p->flags |= TERMP_NOLPAD | TERMP_NOSPACE;
- term_word(p, buf);
+ term_word(p, m->date);
term_flushln(p);
p->offset = p->rmargin;
@@ -444,7 +440,7 @@ print_mdoc_foot(struct termp *p, const v
p->flags &= ~TERMP_NOBREAK;
p->flags |= TERMP_NOLPAD | TERMP_NOSPACE;
- term_word(p, os);
+ term_word(p, m->os);
term_flushln(p);
p->offset = 0;
Index: mdoc_validate.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc_validate.c,v
retrieving revision 1.88
diff -u -p -r1.88 mdoc_validate.c
--- mdoc_validate.c 6 Feb 2011 17:33:21 -0000 1.88
+++ mdoc_validate.c 3 Mar 2011 23:56:35 -0000
@@ -1,6 +1,7 @@
/* $Id: mdoc_validate.c,v 1.88 2011/02/06 17:33:21 schwarze Exp $ */
/*
* Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
+ * Copyright (c) 2011 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
@@ -216,7 +217,7 @@ const struct valids mdoc_valids[MDOC_MAX
{ NULL, posts_text }, /* Xr */
{ NULL, posts_text }, /* %A */
{ NULL, posts_text }, /* %B */ /* FIXME: can be used outside Rs/Re. */
- { NULL, posts_text }, /* %D */ /* FIXME: check date with mandoc_a2time(). */
+ { NULL, posts_text }, /* %D */
{ NULL, posts_text }, /* %I */
{ NULL, posts_text }, /* %J */
{ NULL, posts_text }, /* %N */
@@ -910,7 +911,7 @@ static int
pre_dt(PRE_ARGS)
{
- if (0 == mdoc->meta.date || mdoc->meta.os)
+ if (NULL == mdoc->meta.date || mdoc->meta.os)
mdoc_nmsg(mdoc, n, MANDOCERR_PROLOGOOO);
if (mdoc->meta.title)
@@ -923,7 +924,7 @@ static int
pre_os(PRE_ARGS)
{
- if (NULL == mdoc->meta.title || 0 == mdoc->meta.date)
+ if (NULL == mdoc->meta.title || NULL == mdoc->meta.date)
mdoc_nmsg(mdoc, n, MANDOCERR_PROLOGOOO);
if (mdoc->meta.os)
@@ -1962,23 +1963,19 @@ post_dd(POST_ARGS)
char buf[DATESIZE];
struct mdoc_node *n;
- n = mdoc->last;
+ if (mdoc->meta.date)
+ free(mdoc->meta.date);
- if (NULL == n->child) {
- mdoc->meta.date = time(NULL);
+ n = mdoc->last->child;
+ if (NULL == n || '\0' == n->string[0]) {
+ mdoc->meta.date = mandoc_normdate(NULL);
return(1);
}
- if ( ! concat(mdoc, buf, n->child, DATESIZE))
+ if ( ! concat(mdoc, buf, n, DATESIZE))
return(0);
- mdoc->meta.date = mandoc_a2time
- (MTIME_MDOCDATE | MTIME_CANONICAL, buf);
-
- if (0 == mdoc->meta.date) {
- mdoc_nmsg(mdoc, n, MANDOCERR_BADDATE);
- mdoc->meta.date = time(NULL);
- }
+ mdoc->meta.date = mandoc_normdate(buf);
return(1);
}
Index: out.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/out.h,v
retrieving revision 1.8
diff -u -p -r1.8 out.h
--- out.h 30 Jan 2011 16:05:29 -0000 1.8
+++ out.h 3 Mar 2011 23:56:35 -0000
@@ -17,8 +17,6 @@
#ifndef OUT_H
#define OUT_H
-#define DATESIZ 24
-
__BEGIN_DECLS
struct roffcol {
--
To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: clean up date handling
2011-03-04 0:14 clean up date handling Ingo Schwarze
@ 2011-03-04 22:24 ` Ingo Schwarze
2011-03-05 0:15 ` Ingo Schwarze
0 siblings, 1 reply; 5+ messages in thread
From: Ingo Schwarze @ 2011-03-04 22:24 UTC (permalink / raw)
To: tech; +Cc: Tim van der Molen, jmc
Hi,
replying to myself...
> Tim recently noticed inconsistencies between mandoc date handling
> and what the manuals say about it. Having a closer look, i came
> to the conclusion that this is one of the rare fields where
> compatibility with new groff really makes no sense because groff
> makes too many bad decisions. Besides, it is well-known that
> this area is one of the worst sources of warnings, and i feel
> these warnings are not really useful.
>
> So, here is a radical cleanup of date handling (-99 +69).
Updated version -97 +85.
> Basically, it store all dates as strings everywhere, which simplifies
> handling a lot, in particular in the frontends, and it tries the three
> most common formats everywhere; in case of mismatch it just copies the
> date string verbatim, or if there is no string at all, it uses the
> current date.
>
> This needs more testing, but i won't continue on it tonight, so i'm
> showing it around for comments.
>
> Note that i removed all warnings. Maybe that's ok.
> Maybe we should sparingly restore a few.
> I'm going to reconsider that aspect.
I have restored some warnings - both those issued when the date
is missing completely and those issued when it cannot be parsed,
but i suggest accepting all formats everywhere to reduce noise.
It's hard to see where exactly date format rules come from, and
practical usage varies wildly. In case we find other common input
formats in the wild, we can simply add them to mandoc_normdate().
This is now tested as well: Both systematically exercising all
code paths and running a build of all OpenBSD manuals.
OK to commit?
> I'm planning to look at the manuals once we agree about the
> functionality we want.
I'm now going to look at the manuals to document the changes,
as far as that's required.
Yours,
Ingo
P.S.
By the way, Tim's original suggestion to remove ewarn_ge1
from posts_dd is now contained in the diff as well,-)
because the warning about a missing date is now handled
in mandoc_normdate().
Index: libmandoc.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/libmandoc.h,v
retrieving revision 1.8
diff -u -p -r1.8 libmandoc.h
--- libmandoc.h 3 Jan 2011 22:27:21 -0000 1.8
+++ libmandoc.h 4 Mar 2011 22:07:55 -0000
@@ -25,11 +25,7 @@ char *mandoc_strdup(const char *);
void *mandoc_malloc(size_t);
void *mandoc_realloc(void *, size_t);
char *mandoc_getarg(char **, mandocmsg, void *, int, int *);
-time_t mandoc_a2time(int, const char *);
-#define MTIME_CANONICAL (1 << 0)
-#define MTIME_REDUCED (1 << 1)
-#define MTIME_MDOCDATE (1 << 2)
-#define MTIME_ISO_8601 (1 << 3)
+char *mandoc_normdate(char *, mandocmsg, void *, int, int);
int mandoc_eos(const char *, size_t, int);
int mandoc_hyph(const char *, const char *);
Index: main.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/main.c,v
retrieving revision 1.72
diff -u -p -r1.72 main.c
--- main.c 6 Feb 2011 17:33:20 -0000 1.72
+++ main.c 4 Mar 2011 22:07:56 -0000
@@ -113,7 +113,8 @@ static const char * const mandocerrs[MAN
"no title in document",
"document title should be all caps",
"unknown manual section",
- "cannot parse date argument",
+ "date missing, using today's date",
+ "cannot parse date, using it verbatim",
"prologue macros out of order",
"duplicate prologue macro",
"macro not allowed in prologue",
Index: man.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/man.c,v
retrieving revision 1.55
diff -u -p -r1.55 man.c
--- man.c 10 Feb 2011 00:06:30 -0000 1.55
+++ man.c 4 Mar 2011 22:07:56 -0000
@@ -142,8 +142,8 @@ man_free1(struct man *man)
free(man->meta.title);
if (man->meta.source)
free(man->meta.source);
- if (man->meta.rawdate)
- free(man->meta.rawdate);
+ if (man->meta.date)
+ free(man->meta.date);
if (man->meta.vol)
free(man->meta.vol);
if (man->meta.msec)
Index: man.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/man.h,v
retrieving revision 1.34
diff -u -p -r1.34 man.h
--- man.h 16 Jan 2011 02:56:47 -0000 1.34
+++ man.h 4 Mar 2011 22:07:56 -0000
@@ -75,8 +75,7 @@ enum man_type {
*/
struct man_meta {
char *msec; /* `TH' section (1, 3p, etc.) */
- time_t date; /* `TH' normalised date */
- char *rawdate; /* raw `TH' date */
+ char *date; /* `TH' normalised date */
char *vol; /* `TH' volume */
char *title; /* `TH' title (e.g., FOO) */
char *source; /* `TH' source (e.g., GNU) */
Index: man_html.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/man_html.c,v
retrieving revision 1.34
diff -u -p -r1.34 man_html.c
--- man_html.c 17 Jan 2011 00:15:19 -0000 1.34
+++ man_html.c 4 Mar 2011 22:07:56 -0000
@@ -330,12 +330,6 @@ man_root_post(MAN_ARGS)
{
struct htmlpair tag[3];
struct tag *t, *tt;
- char b[DATESIZ];
-
- if (m->rawdate)
- strlcpy(b, m->rawdate, DATESIZ);
- else
- time2a(m->date, b, DATESIZ);
PAIR_SUMMARY_INIT(&tag[0], "Document Footer");
PAIR_CLASS_INIT(&tag[1], "foot");
@@ -353,7 +347,7 @@ man_root_post(MAN_ARGS)
PAIR_CLASS_INIT(&tag[0], "foot-date");
print_otag(h, TAG_TD, 1, tag);
- print_text(h, b);
+ print_text(h, m->date);
print_stagq(h, tt);
PAIR_CLASS_INIT(&tag[0], "foot-os");
Index: man_term.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/man_term.c,v
retrieving revision 1.64
diff -u -p -r1.64 man_term.c
--- man_term.c 25 Jan 2011 12:35:07 -0000 1.64
+++ man_term.c 4 Mar 2011 22:07:56 -0000
@@ -939,24 +939,18 @@ print_man_nodelist(DECL_ARGS)
static void
print_man_foot(struct termp *p, const void *arg)
{
- char buf[DATESIZ];
const struct man_meta *meta;
meta = (const struct man_meta *)arg;
term_fontrepl(p, TERMFONT_NONE);
- if (meta->rawdate)
- strlcpy(buf, meta->rawdate, DATESIZ);
- else
- time2a(meta->date, buf, DATESIZ);
-
term_vspace(p);
term_vspace(p);
term_vspace(p);
p->flags |= TERMP_NOSPACE | TERMP_NOBREAK;
- p->rmargin = p->maxrmargin - term_strlen(p, buf);
+ p->rmargin = p->maxrmargin - term_strlen(p, meta->date);
p->offset = 0;
/* term_strlen() can return zero. */
@@ -974,7 +968,7 @@ print_man_foot(struct termp *p, const vo
p->rmargin = p->maxrmargin;
p->flags &= ~TERMP_NOBREAK;
- term_word(p, buf);
+ term_word(p, meta->date);
term_flushln(p);
}
Index: man_validate.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/man_validate.c,v
retrieving revision 1.40
diff -u -p -r1.40 man_validate.c
--- man_validate.c 17 Jan 2011 00:15:19 -0000 1.40
+++ man_validate.c 4 Mar 2011 22:07:56 -0000
@@ -187,8 +187,9 @@ check_root(CHKARGS)
*/
m->meta.title = mandoc_strdup("unknown");
- m->meta.date = time(NULL);
m->meta.msec = mandoc_strdup("1");
+ m->meta.date = mandoc_normdate(NULL,
+ m->msg, m->data, n->line, n->pos);
}
return(1);
@@ -370,6 +371,7 @@ static int
post_TH(CHKARGS)
{
const char *p;
+ int line, pos;
if (m->meta.title)
free(m->meta.title);
@@ -379,12 +381,13 @@ post_TH(CHKARGS)
free(m->meta.source);
if (m->meta.msec)
free(m->meta.msec);
- if (m->meta.rawdate)
- free(m->meta.rawdate);
+ if (m->meta.date)
+ free(m->meta.date);
- m->meta.title = m->meta.vol = m->meta.rawdate =
+ line = n->line;
+ pos = n->pos;
+ m->meta.title = m->meta.vol = m->meta.date =
m->meta.msec = m->meta.source = NULL;
- m->meta.date = 0;
/* ->TITLE<- MSEC DATE SOURCE VOL */
@@ -412,24 +415,12 @@ post_TH(CHKARGS)
/* TITLE MSEC ->DATE<- SOURCE VOL */
- /*
- * Try to parse the date. If this works, stash the epoch (this
- * is optimal because we can reformat it in the canonical form).
- * If it doesn't parse, isn't specified at all, or is an empty
- * string, then use the current date.
- */
-
if (n)
n = n->next;
- if (n && n->string && *n->string) {
- m->meta.date = mandoc_a2time
- (MTIME_ISO_8601, n->string);
- if (0 == m->meta.date) {
- man_nmsg(m, n, MANDOCERR_BADDATE);
- m->meta.rawdate = mandoc_strdup(n->string);
- }
- } else
- m->meta.date = time(NULL);
+ if (n)
+ pos = n->pos;
+ m->meta.date = mandoc_normdate(n ? n->string : NULL,
+ m->msg, m->data, line, pos);
/* TITLE MSEC DATE ->SOURCE<- VOL */
Index: mandoc.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.c,v
retrieving revision 1.21
diff -u -p -r1.21 mandoc.c
--- mandoc.c 3 Jan 2011 22:27:21 -0000 1.21
+++ mandoc.c 4 Mar 2011 22:07:56 -0000
@@ -27,8 +27,10 @@
#include "mandoc.h"
#include "libmandoc.h"
-static int a2time(time_t *, const char *, const char *);
+#define DATESIZE 32
+static int a2time(time_t *, const char *, const char *);
+static char *time2a(time_t);
int
mandoc_special(char *p)
@@ -376,38 +378,55 @@ a2time(time_t *t, const char *fmt, const
}
-/*
- * Convert from a manual date string (see mdoc(7) and man(7)) into a
- * date according to the stipulated date type.
- */
-time_t
-mandoc_a2time(int flags, const char *p)
+static char *
+time2a(time_t t)
+{
+ struct tm tm;
+ char buf[DATESIZE];
+ char *p;
+ size_t nsz, rsz;
+ int isz;
+
+ localtime_r(&t, &tm);
+
+ p = buf;
+ rsz = DATESIZE;
+
+ if (0 == (nsz = strftime(p, rsz, "%B ", &tm)))
+ return(NULL);
+
+ p += (int)nsz;
+ rsz -= nsz;
+
+ if (-1 == (isz = snprintf(p, rsz, "%d, ", tm.tm_mday)))
+ return(NULL);
+
+ p += isz;
+ rsz -= isz;
+
+ return(strftime(p, rsz, "%Y", &tm) ? buf : NULL);
+}
+
+
+char *
+mandoc_normdate(char *in, mandocmsg msg, void *data, int ln, int pos)
{
+ char *out;
time_t t;
- if (MTIME_MDOCDATE & flags) {
- if (0 == strcmp(p, "$" "Mdocdate$"))
- return(time(NULL));
- if (a2time(&t, "$" "Mdocdate: %b %d %Y $", p))
- return(t);
- }
-
- if (MTIME_CANONICAL & flags || MTIME_REDUCED & flags)
- if (a2time(&t, "%b %d, %Y", p))
- return(t);
-
- if (MTIME_ISO_8601 & flags)
- if (a2time(&t, "%Y-%m-%d", p))
- return(t);
-
- if (MTIME_REDUCED & flags) {
- if (a2time(&t, "%d, %Y", p))
- return(t);
- if (a2time(&t, "%Y", p))
- return(t);
+ if (NULL == in || '\0' == *in ||
+ 0 == strcmp(in, "$" "Mdocdate$")) {
+ (*msg)(MANDOCERR_NODATE, data, ln, pos, NULL);
+ time(&t);
+ }
+ else if (!a2time(&t, "$" "Mdocdate: %b %d %Y $", in) &&
+ !a2time(&t, "%b %d, %Y", in) &&
+ !a2time(&t, "%Y-%m-%d", in)) {
+ (*msg)(MANDOCERR_BADDATE, data, ln, pos, NULL);
+ t = 0;
}
-
- return(0);
+ out = t ? time2a(t) : NULL;
+ return(mandoc_strdup(out ? out : in));
}
Index: mandoc.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.h,v
retrieving revision 1.33
diff -u -p -r1.33 mandoc.h
--- mandoc.h 10 Feb 2011 00:06:30 -0000 1.33
+++ mandoc.h 4 Mar 2011 22:07:56 -0000
@@ -50,7 +50,8 @@ enum mandocerr {
MANDOCERR_NOTITLE, /* no title in document */
MANDOCERR_UPPERCASE, /* document title should be all caps */
MANDOCERR_BADMSEC, /* unknown manual section */
- MANDOCERR_BADDATE, /* cannot parse date argument */
+ MANDOCERR_NODATE, /* date missing, using today's date */
+ MANDOCERR_BADDATE, /* cannot parse date, using it verbatim */
MANDOCERR_PROLOGOOO, /* prologue macros out of order */
MANDOCERR_PROLOGREP, /* duplicate prologue macro */
MANDOCERR_BADPROLOG, /* macro not allowed in prologue */
Index: mdoc.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc.c,v
retrieving revision 1.79
diff -u -p -r1.79 mdoc.c
--- mdoc.c 10 Feb 2011 00:06:30 -0000 1.79
+++ mdoc.c 4 Mar 2011 22:07:57 -0000
@@ -314,8 +314,9 @@ mdoc_macro(MACRO_PROT_ARGS)
m->meta.vol = mandoc_strdup("LOCAL");
if (NULL == m->meta.os)
m->meta.os = mandoc_strdup("LOCAL");
- if (0 == m->meta.date)
- m->meta.date = time(NULL);
+ if (NULL == m->meta.date)
+ m->meta.date = mandoc_normdate(NULL,
+ m->msg, m->data, line, ppos);
m->flags |= MDOC_PBODY;
}
Index: mdoc.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc.h,v
retrieving revision 1.43
diff -u -p -r1.43 mdoc.h
--- mdoc.h 30 Jan 2011 17:41:59 -0000 1.43
+++ mdoc.h 4 Mar 2011 22:07:57 -0000
@@ -231,7 +231,7 @@ struct mdoc_meta {
char *msec; /* `Dt' section (1, 3p, etc.) */
char *vol; /* `Dt' volume (implied) */
char *arch; /* `Dt' arch (i386, etc.) */
- time_t date; /* `Dd' normalised date */
+ char *date; /* `Dd' normalised date */
char *title; /* `Dt' title (FOO, etc.) */
char *os; /* `Os' system (OpenBSD, etc.) */
char *name; /* leading `Nm' name */
Index: mdoc_html.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc_html.c,v
retrieving revision 1.52
diff -u -p -r1.52 mdoc_html.c
--- mdoc_html.c 6 Feb 2011 22:56:45 -0000 1.52
+++ mdoc_html.c 4 Mar 2011 22:07:57 -0000
@@ -488,9 +488,6 @@ mdoc_root_post(MDOC_ARGS)
{
struct htmlpair tag[3];
struct tag *t, *tt;
- char b[DATESIZ];
-
- time2a(m->date, b, DATESIZ);
PAIR_SUMMARY_INIT(&tag[0], "Document Footer");
PAIR_CLASS_INIT(&tag[1], "foot");
@@ -510,7 +507,7 @@ mdoc_root_post(MDOC_ARGS)
PAIR_CLASS_INIT(&tag[0], "foot-date");
print_otag(h, TAG_TD, 1, tag);
- print_text(h, b);
+ print_text(h, m->date);
print_stagq(h, tt);
PAIR_CLASS_INIT(&tag[0], "foot-os");
Index: mdoc_term.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc_term.c,v
retrieving revision 1.129
diff -u -p -r1.129 mdoc_term.c
--- mdoc_term.c 6 Feb 2011 22:56:45 -0000 1.129
+++ mdoc_term.c 4 Mar 2011 22:07:57 -0000
@@ -404,7 +404,6 @@ print_mdoc_node(DECL_ARGS)
static void
print_mdoc_foot(struct termp *p, const void *arg)
{
- char buf[DATESIZ], os[BUFSIZ];
const struct mdoc_meta *m;
m = (const struct mdoc_meta *)arg;
@@ -419,24 +418,21 @@ print_mdoc_foot(struct termp *p, const v
* SYSTEM DATE SYSTEM
*/
- time2a(m->date, buf, DATESIZ);
- strlcpy(os, m->os, BUFSIZ);
-
term_vspace(p);
p->offset = 0;
p->rmargin = (p->maxrmargin -
- term_strlen(p, buf) + term_len(p, 1)) / 2;
+ term_strlen(p, m->date) + term_len(p, 1)) / 2;
p->flags |= TERMP_NOSPACE | TERMP_NOBREAK;
- term_word(p, os);
+ term_word(p, m->os);
term_flushln(p);
p->offset = p->rmargin;
- p->rmargin = p->maxrmargin - term_strlen(p, os);
+ p->rmargin = p->maxrmargin - term_strlen(p, m->os);
p->flags |= TERMP_NOLPAD | TERMP_NOSPACE;
- term_word(p, buf);
+ term_word(p, m->date);
term_flushln(p);
p->offset = p->rmargin;
@@ -444,7 +440,7 @@ print_mdoc_foot(struct termp *p, const v
p->flags &= ~TERMP_NOBREAK;
p->flags |= TERMP_NOLPAD | TERMP_NOSPACE;
- term_word(p, os);
+ term_word(p, m->os);
term_flushln(p);
p->offset = 0;
Index: mdoc_validate.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc_validate.c,v
retrieving revision 1.88
diff -u -p -r1.88 mdoc_validate.c
--- mdoc_validate.c 6 Feb 2011 17:33:21 -0000 1.88
+++ mdoc_validate.c 4 Mar 2011 22:07:58 -0000
@@ -1,6 +1,7 @@
/* $Id: mdoc_validate.c,v 1.88 2011/02/06 17:33:21 schwarze Exp $ */
/*
* Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
+ * Copyright (c) 2011 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
@@ -135,7 +136,7 @@ static v_post posts_bx[] = { post_bx, N
static v_post posts_bool[] = { ebool, NULL };
static v_post posts_eoln[] = { post_eoln, NULL };
static v_post posts_defaults[] = { post_defaults, NULL };
-static v_post posts_dd[] = { ewarn_ge1, post_dd, post_prol, NULL };
+static v_post posts_dd[] = { post_dd, post_prol, NULL };
static v_post posts_dl[] = { post_literal, bwarn_ge1, NULL };
static v_post posts_dt[] = { post_dt, post_prol, NULL };
static v_post posts_fo[] = { hwarn_eq1, bwarn_ge1, NULL };
@@ -216,7 +217,7 @@ const struct valids mdoc_valids[MDOC_MAX
{ NULL, posts_text }, /* Xr */
{ NULL, posts_text }, /* %A */
{ NULL, posts_text }, /* %B */ /* FIXME: can be used outside Rs/Re. */
- { NULL, posts_text }, /* %D */ /* FIXME: check date with mandoc_a2time(). */
+ { NULL, posts_text }, /* %D */
{ NULL, posts_text }, /* %I */
{ NULL, posts_text }, /* %J */
{ NULL, posts_text }, /* %N */
@@ -910,7 +911,7 @@ static int
pre_dt(PRE_ARGS)
{
- if (0 == mdoc->meta.date || mdoc->meta.os)
+ if (NULL == mdoc->meta.date || mdoc->meta.os)
mdoc_nmsg(mdoc, n, MANDOCERR_PROLOGOOO);
if (mdoc->meta.title)
@@ -923,7 +924,7 @@ static int
pre_os(PRE_ARGS)
{
- if (NULL == mdoc->meta.title || 0 == mdoc->meta.date)
+ if (NULL == mdoc->meta.title || NULL == mdoc->meta.date)
mdoc_nmsg(mdoc, n, MANDOCERR_PROLOGOOO);
if (mdoc->meta.os)
@@ -1962,23 +1963,21 @@ post_dd(POST_ARGS)
char buf[DATESIZE];
struct mdoc_node *n;
- n = mdoc->last;
+ if (mdoc->meta.date)
+ free(mdoc->meta.date);
- if (NULL == n->child) {
- mdoc->meta.date = time(NULL);
+ n = mdoc->last;
+ if (NULL == n->child || '\0' == n->child->string[0]) {
+ mdoc->meta.date = mandoc_normdate(NULL,
+ mdoc->msg, mdoc->data, n->line, n->pos);
return(1);
}
if ( ! concat(mdoc, buf, n->child, DATESIZE))
return(0);
- mdoc->meta.date = mandoc_a2time
- (MTIME_MDOCDATE | MTIME_CANONICAL, buf);
-
- if (0 == mdoc->meta.date) {
- mdoc_nmsg(mdoc, n, MANDOCERR_BADDATE);
- mdoc->meta.date = time(NULL);
- }
+ mdoc->meta.date = mandoc_normdate(buf,
+ mdoc->msg, mdoc->data, n->line, n->pos);
return(1);
}
Index: out.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/out.h,v
retrieving revision 1.8
diff -u -p -r1.8 out.h
--- out.h 30 Jan 2011 16:05:29 -0000 1.8
+++ out.h 4 Mar 2011 22:07:58 -0000
@@ -17,8 +17,6 @@
#ifndef OUT_H
#define OUT_H
-#define DATESIZ 24
-
__BEGIN_DECLS
struct roffcol {
--
To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: clean up date handling
2011-03-04 22:24 ` Ingo Schwarze
@ 2011-03-05 0:15 ` Ingo Schwarze
[not found] ` <20110305075314.GC18361@harkle.bramka>
0 siblings, 1 reply; 5+ messages in thread
From: Ingo Schwarze @ 2011-03-05 0:15 UTC (permalink / raw)
To: tech; +Cc: Tim van der Molen, jmc
Hi,
this is how i propose to update the manuals:
- Remove the "Dates" sections in both mdoc(7) and man(7).
Basically, both languages use dates for one macro each,
.Dd and .TH, so we can simply document dates there.
- Regarding mdoc(7) .%D, it doesn't look like formatters
do any checking, so don't talk about required formats,
but do informally recommend the two sanest options.
- Mark the date as required for both mdoc(7) and man(7),
for two reasons: Publishing a document without a date
is a bad idea in general, and formatters tend to behave
strangely when the date is missing.
- For mdoc(7), document the proper format right in the .Dd
synopsis. Make it clear that anything else is not portable.
- More details about mdoc(7) .Dd COMPATIBILITY.
- In man(7), mark up argument placeholders as .Ar, not .Cm.
In case the code changes go in, is this OK as well?
Yours,
Ingo
Index: mdoc.7
===================================================================
RCS file: /cvs/src/share/man/man7/mdoc.7,v
retrieving revision 1.65
diff -u -r1.65 mdoc.7
--- mdoc.7 7 Feb 2011 00:02:50 -0000 1.65
+++ mdoc.7 5 Mar 2011 00:00:31 -0000
@@ -197,34 +197,6 @@
.Ed
.Pp
In free-form mode, quotes are regarded as opaque text.
-.Ss Dates
-There are several macros in
-.Nm
-that require a date argument.
-The canonical form for dates is the American format:
-.Pp
-.D1 Cm Month Day , Year
-.Pp
-The
-.Cm Day
-value is an optionally zero-padded numeral.
-The
-.Cm Month
-value is the full month name.
-The
-.Cm Year
-value is the full four-digit year.
-.Pp
-Reduced form dates are broken-down canonical form dates:
-.Pp
-.D1 Cm Month , Year
-.D1 Cm Year
-.Pp
-Some examples of valid dates follow:
-.Pp
-.D1 "May, 2009" Pq reduced form
-.D1 "2009" Pq reduced form
-.D1 "May 20, 2009" Pq canonical form
.Ss Scaling Widths
Many macros support scaled widths for their arguments, such as
stipulating a two-inch list indentation with the following:
@@ -886,8 +858,10 @@
Publication date of an
.Sx \&Rs
block.
-This should follow the reduced or canonical form syntax described in
-.Sx Dates .
+Recommended formats of arguments are
+.Ar month day , year
+or just
+.Ar year .
.Ss \&%I
Publisher or issuer name of an
.Sx \&Rs
@@ -1469,17 +1443,34 @@
manual.
Its syntax is as follows:
.Pp
-.D1 Pf \. Sx \&Dd Op Ar date
+.D1 Pf \. Sx \&Dd Ar month day , year
.Pp
The
-.Ar date
-may be either
-.Ar $\&Mdocdate$ ,
-which signifies the current manual revision date dictated by
+.Ar month
+is the full english month name, the
+.Ar day
+is an optionally zero-padded numeral, and the
+.Ar year
+is the full four-digit year.
+.Pp
+Other arguments are not portable; the
+.Xr mandoc 1
+utility handles them as follows:
+.Bl -dash -offset 3n -compact
+.It
+To have the date automatically filled in by
.Xr cvs 1 ,
-or instead a valid canonical date as specified by
-.Sx Dates .
-If a date does not conform or is empty, the current date is used.
+the special string
+.Dq $\&Mdocdate$
+can be given as an argument.
+.It
+A few alternative date formats are accepted as well
+and converted to the standard form.
+.It
+If a date string cannot be parsed, it is used verbatim.
+.It
+If no date string is given, the current date is used.
+.El
.Pp
Examples:
.Dl \&.Dd $\&Mdocdate$
@@ -2771,9 +2762,12 @@
\*[hist]
.It
.Sx \&Dd
-without an argument prints
-.Dq Epoch .
-In mandoc, it resolves to the current date.
+with non-standard arguments behaves very strangely.
+When there are three arguments, they are printed verbatim.
+Any other number of arguments is replaced by the current date,
+but without any arguments, the string
+.Dq Epoch
+is printed.
.It
.Sx \&Fl
does not print a dash for an empty argument.
Index: man.7
===================================================================
RCS file: /cvs/src/share/man/man7/man.7,v
retrieving revision 1.16
diff -u -r1.16 man.7
--- man.7 25 Jan 2011 00:37:39 -0000 1.16
+++ man.7 5 Mar 2011 00:00:31 -0000
@@ -118,15 +118,6 @@
.Pp
In macro lines, whitespace delimits arguments and is discarded.
If arguments are quoted, whitespace within the quotes is retained.
-.Ss Dates
-The
-.Sx \&TH
-macro is the only
-.Nm
-macro that requires a date.
-The form for this date is the ISO-8601
-standard
-.Cm YYYY-MM-DD .
.Ss Scaling Widths
Many macros support scaled widths for their arguments, such as
stipulating a two-inch paragraph indentation with the following:
@@ -762,26 +753,27 @@
Sets the title of the manual page with the following syntax:
.Bd -filled -offset indent
.Pf \. Sx \&TH
-.Cm title section
-.Op Cm date Op Cm source Op Cm volume
+.Ar title section date
+.Op Ar source Op Ar volume
.Ed
.Pp
-At least the upper-case document
-.Cm title
-and the manual
-.Cm section
-arguments must be provided.
-The
-.Cm date
-argument should be formatted as described in
-.Sx Dates ,
-but will be printed verbatim if it is not.
-If the date is not specified, the current date is used.
-The
-.Cm source
+Conventionally, the document
+.Ar title
+is given in all caps.
+The recommended
+.Ar date
+format is
+.Sy YYYY-MM-DD
+as specified in the ISO-8601 standard;
+if the argument does not conform, it is printed verbatim.
+If the
+.Ar date
+is empty or not specified, the current date is used.
+The optional
+.Ar source
string specifies the organisation providing the utility.
The
-.Cm volume
+.Ar volume
string replaces the default rendered volume, which is dictated by the
manual section.
.Pp
--
To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: clean up date handling
[not found] ` <20110305075314.GC18361@harkle.bramka>
@ 2011-03-05 19:27 ` Ingo Schwarze
2011-03-06 23:51 ` Kristaps Dzonsons
0 siblings, 1 reply; 5+ messages in thread
From: Ingo Schwarze @ 2011-03-05 19:27 UTC (permalink / raw)
To: Jason McIntyre; +Cc: tech, Tim van der Molen
Hi Jason,
Jason McIntyre wrote on Sat, Mar 05, 2011 at 07:52:50AM +0001:
> On Sat, Mar 05, 2011 at 01:15:40AM +0100, Ingo Schwarze wrote:
[...]
>> +Other arguments are not portable; the
>> +.Xr mandoc 1
>> +utility handles them as follows:
>> +.Bl -dash -offset 3n -compact
>> +.It
>> +To have the date automatically filled in by
>> .Xr cvs 1 ,
>> -or instead a valid canonical date as specified by
>> -.Sx Dates .
>> -If a date does not conform or is empty, the current date is used.
>> +the special string
>> +.Dq $\&Mdocdate$
>> +can be given as an argument.
> shouldn;t you mention this is openbsd only?
Yes, that makes sense.
However, it's just OpenBSD's cvs(1) that is special,
mandoc(1) can handle $Mdocdate$ on any platform,
so i will use this wording:
To have the date automatically filled in by the
.Ox
version of
.Xr cvs 1 ,
the special string
.Dq $\&Mdocdate$
can be given as an argument.
I have fixed your other findings in my tree, so if this goes in,
they will be contained.
Thanks,
Ingo
--
To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: clean up date handling
2011-03-05 19:27 ` Ingo Schwarze
@ 2011-03-06 23:51 ` Kristaps Dzonsons
0 siblings, 0 replies; 5+ messages in thread
From: Kristaps Dzonsons @ 2011-03-06 23:51 UTC (permalink / raw)
To: tech; +Cc: Ingo Schwarze, Jason McIntyre, Tim van der Molen
On 05/03/2011 20:27, Ingo Schwarze wrote:
> Hi Jason,
>
> Jason McIntyre wrote on Sat, Mar 05, 2011 at 07:52:50AM +0001:
>> On Sat, Mar 05, 2011 at 01:15:40AM +0100, Ingo Schwarze wrote:
>
> [...]
>>> +Other arguments are not portable; the
>>> +.Xr mandoc 1
>>> +utility handles them as follows:
>>> +.Bl -dash -offset 3n -compact
>>> +.It
>>> +To have the date automatically filled in by
>>> .Xr cvs 1 ,
>>> -or instead a valid canonical date as specified by
>>> -.Sx Dates .
>>> -If a date does not conform or is empty, the current date is used.
>>> +the special string
>>> +.Dq $\&Mdocdate$
>>> +can be given as an argument.
>
>> shouldn;t you mention this is openbsd only?
>
> Yes, that makes sense.
> However, it's just OpenBSD's cvs(1) that is special,
> mandoc(1) can handle $Mdocdate$ on any platform,
> so i will use this wording:
>
> To have the date automatically filled in by the
> .Ox
> version of
> .Xr cvs 1 ,
> the special string
> .Dq $\&Mdocdate$
> can be given as an argument.
>
> I have fixed your other findings in my tree, so if this goes in,
> they will be contained.
Ingo,
I like these changes very much---I remember writing the date code in the
first versions of mandoc and being very puzzled with the canonical
format (hint: there is none).
I do feel that a "canonical" date format (or set of formats, e.g.,
YYYY-MM-DD, YYYY-MM, YYYY) should be suggested just so that people have
some direction, I agree that warning about it is superfluous.
So please check this in; when the code is committed I'll give it a
closer look-over and we can go from there.
Thanks again,
Kristaps
--
To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2011-03-06 23:52 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-03-04 0:14 clean up date handling Ingo Schwarze
2011-03-04 22:24 ` Ingo Schwarze
2011-03-05 0:15 ` Ingo Schwarze
[not found] ` <20110305075314.GC18361@harkle.bramka>
2011-03-05 19:27 ` Ingo Schwarze
2011-03-06 23:51 ` Kristaps Dzonsons
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).