docbook2mdoc-1.0.0 released

docbook2mdoc-1.0.0 released

[Ingo Schwarze]

Hello,

after doing active development on it for about a month, i just released
version 1.0.0 of the DocBook to mdoc converter, docbook2mdoc(1).

See http://mandoc.bsd.lv/docbook2mdoc/ for all information about the
utility and the release notes http://mandoc.bsd.lv/docbook2mdoc/NEWS
for details about this release.

In a nutshell, docbook2mdoc(1) was brought from experimental status
to an early release that can be considered mostly usable for
production, though no doubt there are still many rough edges.
That's why i called it 1.0.0 and not 1.1.1.

Lots of features were added, formatting was improved in many respects,
and several reorganizations were done with respect to internal code
structure.  The expat library is no longer needed, and no other
dependency is required.

Thanks to Stephen Gregoratto for a number of patches and many useful
reports.

I might submit an article about this release - the motivation, the
architectural decisions involved, and what it is capable of - to
undeadly.org, so maybe check over there in a few days.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: docbook2mdoc-1.0.0 released

[Jan Stary]

Hi Ingo,

> after doing active development on it for about a month, i just released
> version 1.0.0 of the DocBook to mdoc converter, docbook2mdoc(1).

thank you. I just tried it out on the wavpack manpages
https://github.com/janstary/manpages/tree/master/wavpack

One thing I noticed with the mdoc output:

  .It Fl -clean, Fl -clear

mandoc -Tlint complains that

  STYLE: no blank before trailing delimiter

Changing that to

  .It Fl -clean , Fl -clear

gets no complaining for -Tlint.

BTW, is "Fl -option" the preferred way to handle --long-options?

	Jan

--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: docbook2mdoc-1.0.0 released

[Anthony J. Bentley]

Jan Stary writes:
> BTW, is "Fl -option" the preferred way to handle --long-options?

I've seen "Fl -option" and "Fl Fl option" about equally. Personally
I prefer Fl Fl, because in some groff outputs "Fl -option" prints
the first and second - as visibly different characters. Fl Fl also
means that mandoc's tagging support lets me search for "option" instead
of "-option", and that feels more natural to me.

-- 
Anthony J. Bentley
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

hyphen-minus, was: docbook2mdoc-1.0.0 released

[Ingo Schwarze]

Hi Jan & Anthony,

Anthony J. Bentley wrote on Sat, Apr 20, 2019 at 04:56:25PM -0600:
> Jan Stary writes:

>> BTW, is "Fl -option" the preferred way to handle --long-options?

Yes.

> I've seen "Fl -option" and "Fl Fl option" about equally.
> Personally I prefer Fl Fl,

We did that for some time, but generally stopped doing so because
even though the printed output looks correct, it is logically
misleading.  There is only a single option here, not two, and .Fl
without an argument means the special option "-", as it occurs for
example in lprm(1) and tset(1).

  http://mandoc.bsd.lv/mdoc/style/options.html

    (note that already recommends .Fl -option even though it was
     last updated more than two years ago)

> because in some groff outputs "Fl -option" prints
> the first and second - as visibly different characters.

Oh wow.  All the discussion we recently had about whether to
recommend "\-" or "-" as input for desired HYPHEN-MINUS output
was based on the assumption that groff contained, for the man(7)
and mdoc(7) macros, a mapping of '-' to \N'45'.  It does indeed
for UTF-8.  But for PostScript and HTML, '-' actually comes out
as a hyphen from groff, even for manual pages...

How could we possibly miss that after years of delimberation?
I'm so tired of this matter...

> Fl Fl also means that mandoc's tagging support lets me search
> for "option" instead of "-option", and that feels more natural to me.

That works either way:

   $ grep version `man -w openrsync`              
  .Op Fl -version
  .It Fl -version
  Print version and exit.
  protocol version is older than the local protocol version.
  is compatible with rsync protocol version 27
   $ man -k Fl=version | grep rsync               
  openrsync(1) - synchronise local and remote files
   $ man -k Fl~version | grep rsync 
  openrsync(1) - synchronise local and remote files

You would have to go out of your way to not make it work:

   $ man -k Fl~^version | grep rsync
   $ 

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: hyphen-minus, was: docbook2mdoc-1.0.0 released

[Anthony J. Bentley]

Hi Ingo,

Ingo Schwarze writes:
> Hi Jan & Anthony,
>
> Anthony J. Bentley wrote on Sat, Apr 20, 2019 at 04:56:25PM -0600:
> > Jan Stary writes:
>
> >> BTW, is "Fl -option" the preferred way to handle --long-options?
>
> Yes.
>
> > I've seen "Fl -option" and "Fl Fl option" about equally.
> > Personally I prefer Fl Fl,
>
> We did that for some time, but generally stopped doing so because
> even though the printed output looks correct, it is logically
> misleading.

I remember that conclusion, but I simply don't agree with the
prescriptivism in this particular case.

> There is only a single option here, not two, and .Fl
> without an argument means the special option "-", as it occurs for
> example in lprm(1) and tset(1).

"Fl abcd" could mean an option called "abcd" as in xterm(1) or "-a -b
-c -d" as in normal getopt usage. I don't see how "Fl Fl may be
considered to collapse into a single option" is inherently worse than
that, especially as the pattern is seen in real-world manpages.

> > because in some groff outputs "Fl -option" prints
> > the first and second - as visibly different characters.
>
> Oh wow.  All the discussion we recently had about whether to
> recommend "\-" or "-" as input for desired HYPHEN-MINUS output
> was based on the assumption that groff contained, for the man(7)
> and mdoc(7) macros, a mapping of '-' to \N'45'.  It does indeed
> for UTF-8.  But for PostScript and HTML, '-' actually comes out
> as a hyphen from groff, even for manual pages...
>
> How could we possibly miss that after years of delimberation?
> I'm so tired of this matter...

I am quite sure I've mentioned this before in our voluminous discussion
on this subject... hopefully we can avoid re-litigating it, since I hate
the topic as much as you do!

> > Fl Fl also means that mandoc's tagging support lets me search
> > for "option" instead of "-option", and that feels more natural to me.
>
> That works either way:
>
>    $ grep version `man -w openrsync`              
>   .Op Fl -version
>   .It Fl -version
>   Print version and exit.
>   protocol version is older than the local protocol version.
>   is compatible with rsync protocol version 27
>    $ man -k Fl=version | grep rsync               
>   openrsync(1) - synchronise local and remote files
>    $ man -k Fl~version | grep rsync 
>   openrsync(1) - synchronise local and remote files
>
> You would have to go out of your way to not make it work:
>
>    $ man -k Fl~^version | grep rsync
>    $ 

Try "man openrsync", then ":tversion". That's what I was referring to.

-- 
Anthony J. Bentley
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: docbook2mdoc-1.0.0 released

[Stephen Gregoratto]

My vote goes to Fl -option due to how mandoc handles Fl Fl in HTML 
output. Take this example:

  .Bl -tag -width Ds
  .It Fl Fl option
  Foo
  .It Fl -option
  Bar
  .El

On mandoc 1.14.5, the option list is output as follows:

<dl class="Bl-tag">
  <dt>
    <code class="Fl">-</code><code class="Fl">-option</code>
  </dt>
  <dd>Foo</dd>
  <dt>
    <a class="permalink" href="#-option">
      <code class="Fl" id="-option">--option</code>
    </a>
  </dt>
  <dd>Bar</dd>
</dl>

Notice how the Fl -option gets enclosed in an "<a>" link whilst the Fl 
Fl option doesn't? This comes in handy when you have to reference the 
option later as it can link to it's definition in the option list.

On reflection this does seem like a workaround for buggy output.
-- 
Stephen Gregoratto
PGP: 3FC6 3D0E 2801 C348 1C44 2D34 A80C 0F8E 8BAB EC8B
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: docbook2mdoc-1.0.0 released

[Ingo Schwarze]

Hi Stephen,

Stephen Gregoratto wrote on Sun, Apr 21, 2019 at 09:26:32PM +1000:

> My vote goes to Fl -option due to how mandoc handles Fl Fl
> in HTML output.

That isn't a very strong argument.
Best markup practice ought to be governed by what the markup means,
not by how individual output modes represent it.

> Take this example:
> 
>   .Bl -tag -width Ds
>   .It Fl Fl option
>   Foo
>   .It Fl -option
>   Bar
>   .El
> 
> On mandoc 1.14.5, the option list is output as follows:
> 
> <dl class="Bl-tag">
>   <dt>
>     <code class="Fl">-</code><code class="Fl">-option</code>
>   </dt>
>   <dd>Foo</dd>
>   <dt>
>     <a class="permalink" href="#-option">
>       <code class="Fl" id="-option">--option</code>
>     </a>
>   </dt>
>   <dd>Bar</dd>
> </dl>
> 
> Notice how the Fl -option gets enclosed in an "<a>" link whilst the Fl 
> Fl option doesn't? This comes in handy when you have to reference the 
> option later as it can link to it's definition in the option list.

Right.  This is because in the case of ".It Fl", mandoc is able to
figure out that this is likely the authoritative description of the
command line option.  By contrast, in the case of ".It Fl Fl",
mandoc is not able to figure out what is going on.  The first "Fl"
is empty, so it cannot be linked to.  A later "Fl" in ".It" cannot
safely be linked to either.  If "Fl" appears in the middle of other
macros, that is usually *not* the authoritative description of the
option.  Hence mandoc writes no permalink, nor a tag in terminal
output mode.

So in an indirect sense, your argument is sound after all.
The idiom "Fl Fl" is not a good idea because it obscures the
semantics.  The loss of the permalink (and of the tag in terminal
output) is a symptom of that degraded semantic clarity.

> On reflection this does seem like a workaround for buggy output.

No, the output is not buggy, but carefully designed.

It is not a bug, but a feature that not every .Fl macro creates a
permalink.  As a matter of fact, the majority of .Fl macros should
not create permalinks.  Most of them are merely passing mentions
of options in the middle of text describing other matters.

Macros only create permalinks when there are clear indications
that they introduce an authoritative description.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: docbook2mdoc-1.0.0 released

[Ingo Schwarze]

Hi Jan,

Jan Stary wrote on Sat, Apr 20, 2019 at 09:03:31PM +0200:

> https://github.com/janstary/manpages/tree/master/wavpack
> 
> One thing I noticed with the mdoc output:
> 
>   .It Fl -clean, Fl -clear

You found a bug, and i fixed it with the commit below.

Thanks for reporting,
  Ingo


Log Message:
-----------
When <term> contains a macro-generating element,
the subsequent comma needs spacing.
Fixing a bug reported by Jan Stary <hans at stare dot cz>.

Modified Files:
--------------
    docbook2mdoc:
        docbook2mdoc.c

Revision Data
-------------
Index: docbook2mdoc.c
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/docbook2mdoc.c,v
retrieving revision 1.132
retrieving revision 1.133
diff -Ldocbook2mdoc.c -Ldocbook2mdoc.c -u -p -r1.132 -r1.133
--- docbook2mdoc.c
+++ docbook2mdoc.c
@@ -929,16 +929,17 @@ pnode_printrefentry(struct format *f, st
 static void
 pnode_printvarlistentry(struct format *f, struct pnode *n)
 {
-	struct pnode	*nc, *nn;
-	int		 first = 1;
+	struct pnode	*nc, *nn, *ncc;
+	int		 comma;
 
 	macro_open(f, "It");
 	f->parastate = PARA_HAVE;
 	f->flags |= FMT_IMPL;
+	comma = -1;
 	TAILQ_FOREACH_SAFE(nc, &n->childq, child, nn) {
 		if (nc->node != NODE_TERM && nc->node != NODE_GLOSSTERM)
 			continue;
-		if (first == 0) {
+		if (comma != -1) {
 			switch (f->linestate) {
 			case LINE_NEW:
 				break;
@@ -946,14 +947,15 @@ pnode_printvarlistentry(struct format *f
 				print_text(f, ",", 0);
 				break;
 			case LINE_MACRO:
-				macro_addarg(f, ",", 0);
+				macro_addarg(f, ",", comma);
 				break;
 			}
 		}
 		f->parastate = PARA_HAVE;
+		comma = (ncc = TAILQ_FIRST(&nc->childq)) == NULL ||
+		    pnode_class(ncc->node) == CLASS_TEXT ? 0 : ARG_SPACE;
 		pnode_print(f, nc);
 		pnode_unlink(nc);
-		first = 0;
 	}
 	macro_close(f);
 	f->parastate = PARA_HAVE;
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv