call for testing: mandoc-1.13.5 release candidate

call for testing: mandoc-1.13.5 release candidate

[Ingo Schwarze]

Hi,

now that mandoc-1.14.1 is out of the door, i'm planning to release
the SQLite3-compat version mandoc-1.13.5 soon.  A release candidate
tarball is available for testing:

  http://mdocml.bsd.lv/snapshots/mdocml-1.13.5rc1.tar.gz

Both reports of successes and failures are welcome!


Mandoc 1.13.5 is a backward compatibility maintenance release
containing all the improvements of 1.14.1 except the switch away
from SQLite3 and except catman(8).  It is intended exclusively for
-stable operating systems using mandoc-based apropos(1) who cannot
change the database format just like that - notably FreeBSD-stable.
Everybody else is encouraged to use the 1.14 branch instead because
the 1.14 database format is smaller and faster, the 1.14 makewhatis(8)
has some functionality improvements that could not be ported back,
and because the new code got better testing coverage, so there is
a lower risk of bugs in 1.14.1.


In a nutshell, the basic testing procedure is:

 $ ./configure
 $ make
 $ make regress

For more details, see the INSTALL file in the tarball.
Note that the regression suite does NOT test the database
functionality at all, so please check manually that the database
functionality you need works for you.  One minimal way to do that
looks like this:

 mkdir Test
 mkdir Test/man1
 mkdir Test/man3
 mkdir Test/man5
 mkdir Test/man7
 mkdir Test/man8
 cp *.1 Test/man1
 cp *.3 Test/man3
 cp *.5 Test/man5
 cp *.7 Test/man7
 cp *.8 Test/man8
 ln -s mandoc makewhatis
 ln -s mandoc man
 ./makewhatis Test

Then set "export MANPATH=Test" and play around with "./man -k".
Of course, it is better to try something similar with your real
manual page tree.


Optionally, you can run

 $ echo BUILD_CGI=1 > configure.local
 $ cp cgi.h.example cgi.h

before ./configure, but it is not very important.
I don't expect that anybody will run a 1.13.5 man.cgi(8) server.

Thank you for your support!
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: call for testing: mandoc-1.13.5 release candidate

[Jan Stary]

Hi Ingo,

> now that mandoc-1.14.1 is out of the door, i'm planning to release
> the SQLite3-compat version mandoc-1.13.5 soon.  A release candidate
> tarball is available for testing:
> http://mdocml.bsd.lv/snapshots/mdocml-1.13.5rc1.tar.gz
> Both reports of successes and failures are welcome!

I don't know if this is a bug or intended behaviour.
It certainly is not specific to 1.13.5rc1.

On systems where I don't have root (mostly linuxes),
I often install mdocml as a manpage formatter of choice into $HOME,
and alias 'man' as 'man -m $HOME/man' for some third-party software
which I can only install in $HOME.

Everything works as expected, except man -l

  $ alias man="man -m $HOME/man"
  $ man -l /usr/share/man/man1/ls.1.gz
  man: -m /home/hans/man: Bad argument

  $ unalias man
  $ man -l /usr/share/man/man1/ls.1.gz	# works OK

Should -m be ignored with -l, just like -M path and -s section?

	Jan

--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: call for testing: mandoc-1.13.5 release candidate

[Ingo Schwarze]

Hi Jan,

Jan Stary wrote on Sat, Feb 25, 2017 at 01:34:26PM +0100:

> I don't know if this is a bug or intended behaviour.
> It certainly is not specific to 1.13.5rc1.
> 
> On systems where I don't have root (mostly linuxes),
> I often install mdocml as a manpage formatter of choice into $HOME,
> and alias 'man' as 'man -m $HOME/man' for some third-party software
> which I can only install in $HOME.
> 
> Everything works as expected, except man -l
> 
>   $ alias man="man -m $HOME/man"
>   $ man -l /usr/share/man/man1/ls.1.gz
>   man: -m /home/hans/man: Bad argument
> 
>   $ unalias man
>   $ man -l /usr/share/man/man1/ls.1.gz	# works OK
> 
> Should -m be ignored with -l, just like -M path and -s section?

the fact that the traditional mandoc(1) -m input format and man(1) -m
prepend to manpath options conflict with each other is a mess.
That said, input format specification is becoming less and less
relevant, it is almost never needed nowadays.  So i went the
direction you suggested.

Even is someone mistypes -mdoc - like in "mandoc -mdco" - it will
almost always just work, at least for legitimate manual page files.
The only case i can think of where it might fail in surprising ways
is in artificial testing like in

   $ echo .Ox | mandoc -mdco

But even there, the man(7)-style output formatting provides a clue
what went wrong, and if people are still confused, adding -Wall
provides yet another clue:

   $ echo .Ox | mandoc -mdco -Wall
  mandoc: <stdin>:1:2: ERROR: skipping unknown macro: .Ox

That makes it obvious that the wrong macro set was used for parsing.

See below for the commit.

Thanks for the report,
  Ingo


Log Message:
-----------
Silently ignore invalid -m input formats rather than erroring out.
As observed by Jan Stary <hans at stare dot cz>, this is useful such 
that after 'alias man="man -m $HOME/man"', 'man -l foo.1' still works.
Simplify and shorten the description of -m, and use .Ic for macros.

Modified Files:
--------------
    mdocml:
        main.c
        mandoc.1

Revision Data
-------------
Index: mandoc.1
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mandoc.1,v
retrieving revision 1.179
retrieving revision 1.180
diff -Lmandoc.1 -Lmandoc.1 -u -p -r1.179 -r1.180
--- mandoc.1
+++ mandoc.1
@@ -26,7 +26,7 @@
 .Op Fl acfhkl
 .Op Fl I Cm os Ns = Ns Ar name
 .Op Fl K Ar encoding
-.Op Fl m Ns Ar format
+.Op Fl mdoc | man
 .Op Fl O Ar option
 .Op Fl T Ar output
 .Op Fl W Ar level
@@ -44,9 +44,7 @@ reads
 .Xr mdoc 7
 or
 .Xr man 7
-text from stdin, implying
-.Fl m Ns Cm andoc ,
-and produces
+text from stdin and produces
 .Fl T Cm locale
 output.
 .Pp
@@ -84,10 +82,10 @@ Override the default operating system
 .Ar name
 for the
 .Xr mdoc 7
-.Sq \&Os
+.Ic \&Os
 and for the
 .Xr man 7
-.Sq \&TH
+.Ic \&TH
 macro.
 .It Fl K Ar encoding
 Specify the input encoding.
@@ -138,13 +136,28 @@ Also reverts any earlier
 and
 .Fl k
 options.
-.It Fl m Ns Ar format
-Input format.
-See
-.Sx Input Formats
-for available formats.
-Defaults to
-.Fl m Ns Cm andoc .
+.It Fl mdoc | man
+With
+.Fl mdoc ,
+all input files are interpreted as
+.Xr mdoc 7 .
+With
+.Fl man ,
+all input files are interpreted as
+.Xr man 7 .
+By default, the input language is automatically detected for each file:
+if the the first macro is
+.Ic \&Dd
+or
+.Ic \&Dt ,
+the
+.Xr mdoc 7
+parser is used; otherwise, the
+.Xr man 7
+parser is used.
+With other arguments,
+.Fl m
+is silently ignored.
 .It Fl O Ar option
 Comma-separated output options.
 .It Fl T Ar output
@@ -209,49 +222,6 @@ also supports the options
 described in the
 .Xr apropos 1
 manual.
-.Ss Input Formats
-The
-.Nm
-utility accepts
-.Xr mdoc 7
-and
-.Xr man 7
-input with
-.Fl m Ns Cm doc
-and
-.Fl m Ns Cm an ,
-respectively.
-The
-.Xr mdoc 7
-format is
-.Em strongly
-recommended;
-.Xr man 7
-should only be used for legacy manuals.
-.Pp
-A third option,
-.Fl m Ns Cm andoc ,
-which is also the default, determines encoding on-the-fly: if the first
-non-comment macro is
-.Sq \&Dd
-or
-.Sq \&Dt ,
-the
-.Xr mdoc 7
-parser is used; otherwise, the
-.Xr man 7
-parser is used.
-.Pp
-If multiple
-files are specified with
-.Fl m Ns Cm andoc ,
-each has its file-type determined this way.
-If multiple files are
-specified and
-.Fl m Ns Cm doc
-or
-.Fl m Ns Cm an
-is specified, then this format is used exclusively.
 .Ss Output Formats
 The
 .Nm
@@ -391,7 +361,7 @@ The string
 for example,
 .Ar ../src/%I.html ,
 is used as a template for linked header files (usually via the
-.Sq \&In
+.Ic \&In
 macro).
 Instances of
 .Sq \&%I
@@ -404,7 +374,7 @@ The string
 for example,
 .Ar ../html%S/%N.%S.html ,
 is used as a template for linked manuals (usually via the
-.Sq \&Xr
+.Ic \&Xr
 macro).
 Instances of
 .Sq \&%N
@@ -450,7 +420,7 @@ If the input format is
 .Xr man 7 ,
 the input is copied to the output, expanding any
 .Xr roff 7
-.Sq so
+.Ic so
 requests.
 The parser is also run, and as usual, the
 .Fl W
Index: main.c
===================================================================
RCS file: /home/cvs/mdocml/mdocml/main.c,v
retrieving revision 1.285
retrieving revision 1.286
diff -Lmain.c -Lmain.c -u -p -r1.285 -r1.286
--- main.c
+++ main.c
@@ -93,7 +93,7 @@ static	void		  fs_search(const struct ma
 				const struct manpaths *, int, char**,
 				struct manpage **, size_t *);
 static	int		  koptions(int *, char *);
-static	int		  moptions(int *, char *);
+static	void		  moptions(int *, char *);
 static	void		  mmsg(enum mandocerr, enum mandoclevel,
 				const char *, int, int, const char *);
 static	void		  outdata_alloc(struct curparse *);
@@ -442,8 +442,8 @@ main(int argc, char *argv[])
 	}
 #endif
 
-	if (search.argmode == ARG_FILE && ! moptions(&options, auxpaths))
-		return (int)MANDOCLEVEL_BADARG;
+	if (search.argmode == ARG_FILE)
+		moptions(&options, auxpaths);
 
 	mchars_alloc();
 	curp.mp = mparse_alloc(options, curp.wlevel, mmsg, defos);
@@ -919,24 +919,16 @@ koptions(int *options, char *arg)
 	return 1;
 }
 
-static int
+static void
 moptions(int *options, char *arg)
 {
 
 	if (arg == NULL)
-		/* nothing to do */;
-	else if (0 == strcmp(arg, "doc"))
+		return;
+	if (strcmp(arg, "doc") == 0)
 		*options |= MPARSE_MDOC;
-	else if (0 == strcmp(arg, "andoc"))
-		/* nothing to do */;
-	else if (0 == strcmp(arg, "an"))
+	else if (strcmp(arg, "an") == 0)
 		*options |= MPARSE_MAN;
-	else {
-		warnx("-m %s: Bad argument", arg);
-		return 0;
-	}
-
-	return 1;
 }
 
 static int
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv