Re: mdoc section ordering

["Ulrich Spörlein" <uqs@spoerlein.net>]

On Tue, 11.05.2010 at 14:45:18 +0100, Jason McIntyre wrote:
> On Tue, May 11, 2010 at 01:52:33PM +0200, Ulrich Sp??rlein wrote:
> > Hi,
> > 
> > right now the lint option of mandoc will complain mildly, if the section
> > order of manpages is not in a certain order. This is good.
> > 
> > However, while working on the FreeBSD mdoc corpus, I found that FreeBSD
> > and mdocml diverge on where they think the EXIT STATUS section should be
> > placed.
> > 
> > FreeBSD:                                mdocml:
> > 
> > .Dd Month day, year                     .Dd $Mdocdate$
> > .Os [OPERATING_SYSTEM]                  .Dt mdoc 7
> > .Dt DOCUMENT_TITLE                      .Os
> > 
> > .Sh NAME                                .Sh NAME
> > .Nm name                                .Nm foo
> > .Nd one line description of name        .Nd a description goes here
> > .Sh LIBRARY                             .Sh LIBRARY
> > .Sh SYNOPSIS                            .Sh SYNOPSIS
> > .Sh DESCRIPTION                         .Sh DESCRIPTION
> > .Sh IMPLEMENTATION NOTES                .Sh IMPLEMENTATION NOTES
> > 
> > .Sh RETURN VALUES                       .Sh EXIT STATUS
> > .Sh ENVIRONMENT                         .Sh RETURN VALUES
> > .Sh FILES                               .Sh ENVIRONMENT
> > .Sh EXIT STATUS                         .Sh FILES
> > .Sh EXAMPLES                            .Sh EXAMPLES
> > 
> > .Sh DIAGNOSTICS                         .Sh DIAGNOSTICS
> > .Sh COMPATIBILITY
> > .Sh ERRORS                              .Sh ERRORS
> > .Sh SEE ALSO                            .Sh SEE ALSO
> > .Sh STANDARDS                           .Sh STANDARDS
> > .Sh HISTORY                             .Sh HISTORY
> > .Sh AUTHORS                             .Sh AUTHORS
> >                                         .Sh CAVEATS
> > .Sh BUGS                                .Sh BUGS
> >                                         .Sh SECURITY CONSIDERATIONS
> > 
> > It is desirable that we not diverge in this regard and Ruslan's initial
> > motive for putting EXIT STATUS after FILES in FreeBSD has to do with how
> > POSIX is structuring their manpages.
> > 
> > So I'd like to get some consensus on where we should put EXIT STATUS and
> > I'd also like a vote on if COMPATIBILITY should be included as a
> > standard section enforced by mdocml.
> > 
> > Please discuss!
> > Uli
> > --
> 
> not voting, but i can tell you what is standard for openbsd pages - we
> have neither exit status nor compat sections. we did away with exit
> status i think because it was too silly to have a section just saying
> "the app exits blah"; we did away with COMPATIBILITY because the
> potential overlap with STANDARDS was making the structurer of the pages
> poorer (we just rolled it all in to STANDARDS).
> 
> so i personally wouldn;t want mandoc complaining that these sections
> were missing.

To clarify, none of these sections shall become mandatory. It's just the
ordering that mandoc -Tlint would complain about iff such a section
exist.

I did a quick grep over the OpenBSD tree and it seems that EXIT STATUS
isn't really used at all, and where it is used the ordering is not
impacted as there are no RETURN VALUES, ENVIRONMENT or FILES sections
nearby.

NetBSD however has a couple of pages where FILES or ENVIRONMENT come
after EXIT STATUS and that means one of NetBSD or FreeBSD would need to
change a couple of pages.

Regards,
Uli
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv