* Identifying doc formats
@ 2015-07-07 17:23 Warren Block
2015-07-07 17:30 ` Anthony J. Bentley
0 siblings, 1 reply; 3+ messages in thread
From: Warren Block @ 2015-07-07 17:23 UTC (permalink / raw)
To: discuss
[-- 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
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Identifying doc formats
2015-07-07 17:23 Identifying doc formats Warren Block
@ 2015-07-07 17:30 ` Anthony J. Bentley
2015-07-07 22:22 ` Warren Block
0 siblings, 1 reply; 3+ messages in thread
From: Anthony J. Bentley @ 2015-07-07 17:30 UTC (permalink / raw)
To: discuss
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
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: Identifying doc formats
2015-07-07 17:30 ` Anthony J. Bentley
@ 2015-07-07 22:22 ` Warren Block
0 siblings, 0 replies; 3+ messages in thread
From: Warren Block @ 2015-07-07 22:22 UTC (permalink / raw)
To: discuss
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
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2015-07-07 22:22 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2015-07-07 17:23 Identifying doc formats Warren Block
2015-07-07 17:30 ` Anthony J. Bentley
2015-07-07 22:22 ` Warren Block
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).