Identifying doc formats

Identifying doc formats

[Warren Block]

[-- Attachment #1: Type: text/plain, Size: 1855 bytes --]

Can mandoc just detect and display the input format?

file(1) says both tcpdump.1 and ls.1 in FreeBSD are "troff or 
preprocessor input, ASCII text", although one is man and the other is 
mdoc.


In a related note, the mandoc man page is a bit confusing about the 
input format option.  The synopsis says that input formats are

   [-mformat]

That implies--to me, at least--that it would be used as

   -mmdoc

or

   -mman

But...

   % mandoc -mman tcpdump.1
   man: Bad argument
   % mandoc -man tcpdump.1
   (works)

This seems to imply that the input formats could really be "doc", "an", 
and "andoc", and that's obviously not right.

The existing option might also assume that any future input formats will 
start with an "m".  That could be the way the code checks for the option 
internally, but think big.

This diff, also attached, is less confusing to me:

--- mandoc.1.orig	2015-07-07 11:10:38.756334000 -0600
+++ mandoc.1	2015-07-07 11:16:08.358326000 -0600
@@ -23,7 +23,7 @@
  .Sh SYNOPSIS
  .Nm mandoc
  .Op Fl V
-.Op Fl m Ns Ar format
+.Op Fl mdoc Ns | Ns Fl man Ns | Ns Fl mandoc
  .Op Fl O Ns Ar option
  .Op Fl T Ns Ar output
  .Op Fl W Ns Ar level
@@ -49,7 +49,7 @@
  .Pp
  The arguments are as follows:
  .Bl -tag -width Ds
-.It Fl m Ns Ar format
+.It Fl mdoc Ns | Ns Fl man Ns | Ns Fl mandoc
  Input format.
  See
  .Sx Input Formats

This renders as:

SYNOPSIS
      mandoc [-V] [-mdoc|-man|-mandoc] [-Ooption] [-Toutput] [-Wlevel]
             [file ...]

DESCRIPTION
      The mandoc utility formats UNIX manual pages for display.

      By default, mandoc reads mdoc(7) or man(7) text from stdin, implying
      -mandoc, and produces -Tascii output.

      The arguments are as follows:

      -mdoc|-man|-mandoc
              Input format.  See Input Formats for available formats.  Defaults
              to -mandoc.


Thanks!

[-- Attachment #2: Type: text/plain, Size: 496 bytes --]

--- mandoc.1.orig	2015-07-07 11:10:38.756334000 -0600
+++ mandoc.1	2015-07-07 11:16:08.358326000 -0600
@@ -23,7 +23,7 @@
 .Sh SYNOPSIS
 .Nm mandoc
 .Op Fl V
-.Op Fl m Ns Ar format
+.Op Fl mdoc Ns | Ns Fl man Ns | Ns Fl mandoc
 .Op Fl O Ns Ar option
 .Op Fl T Ns Ar output
 .Op Fl W Ns Ar level
@@ -49,7 +49,7 @@
 .Pp
 The arguments are as follows:
 .Bl -tag -width Ds
-.It Fl m Ns Ar format
+.It Fl mdoc Ns | Ns Fl man Ns | Ns Fl mandoc
 Input format.
 See
 .Sx Input Formats

Re: Identifying doc formats

[Anthony J. Bentley]

Warren Block writes:
> Can mandoc just detect and display the input format?
> 
> file(1) says both tcpdump.1 and ls.1 in FreeBSD are "troff or 
> preprocessor input, ASCII text", although one is man and the other is 
> mdoc.

Yes, in -mandoc mode it is automatically detected; see mandoc(1):

     A third option, -mandoc, which is also the default, determines encoding
     on-the-fly: if the first non-comment macro is ‘Dd’ or ‘Dt’, the mdoc(7)
     parser is used; otherwise, the man(7) parser is used.

> In a related note, the mandoc man page is a bit confusing about the 
> input format option.  The synopsis says that input formats are
> 
>    [-mformat]
> 
> That implies--to me, at least--that it would be used as
> 
>    -mmdoc
> 
> or
> 
>    -mman
> 
> But...
> 
>    % mandoc -mman tcpdump.1
>    man: Bad argument
>    % mandoc -man tcpdump.1
>    (works)
> 
> This seems to imply that the input formats could really be "doc", "an", 
> and "andoc", and that's obviously not right.

This is exactly the case. Troff macro sets are specified to troff via the
-m option. For example, if you look at a groff installation, the following
files are used:

/usr/local/share/groff/1.22.3/tmac/an.tmac
/usr/local/share/groff/1.22.3/tmac/andoc.tmac
/usr/local/share/groff/1.22.3/tmac/doc.tmac

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

Re: Identifying doc formats

[Warren Block]

On Tue, 7 Jul 2015, Anthony J. Bentley wrote:

> Warren Block writes:
>> Can mandoc just detect and display the input format?
>>
>> file(1) says both tcpdump.1 and ls.1 in FreeBSD are "troff or
>> preprocessor input, ASCII text", although one is man and the other is
>> mdoc.
>
> Yes, in -mandoc mode it is automatically detected; see mandoc(1):
>
>     A third option, -mandoc, which is also the default, determines encoding
>     on-the-fly: if the first non-comment macro is ?Dd? or ?Dt?, the mdoc(7)
>     parser is used; otherwise, the man(7) parser is used.

Right, but that is not the goal.  What I'm saying is that file(1) does 
not tell whether a man page is mdoc or man format.  mandoc knows, but 
can it show just the detected format name rather than parsing and 
displaying the man page?

That would also be a nice addition to file(1).

>> In a related note, the mandoc man page is a bit confusing about the
>> input format option.  The synopsis says that input formats are
>>
>>    [-mformat]
>>
>> That implies--to me, at least--that it would be used as
>>
>>    -mmdoc
>>
>> or
>>
>>    -mman
>>
>> But...
>>
>>    % mandoc -mman tcpdump.1
>>    man: Bad argument
>>    % mandoc -man tcpdump.1
>>    (works)
>>
>> This seems to imply that the input formats could really be "doc", "an",
>> and "andoc", and that's obviously not right.
>
> This is exactly the case. Troff macro sets are specified to troff via the
> -m option. For example, if you look at a groff installation, the following
> files are used:
>
> /usr/local/share/groff/1.22.3/tmac/an.tmac
> /usr/local/share/groff/1.22.3/tmac/andoc.tmac
> /usr/local/share/groff/1.22.3/tmac/doc.tmac

That's... well, okay, I believe it.  But that is not how those input 
formats are shown in the mandoc man page currently.  And I agree with 
that, showing "-m(doc|an|andoc)" might be how the program does it 
internally, but does not help make them mnemonic for the user.
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv