From: Jason McIntyre <jmc@kerhand.co.uk>
To: discuss@mdocml.bsd.lv
Subject: Re: mdoc section ordering
Date: Tue, 11 May 2010 14:45:18 +0100 [thread overview]
Message-ID: <20100511134542.GA24992@bramka.kerhand.co.uk> (raw)
In-Reply-To: <20100511115233.GV88504@acme.spoerlein.net>
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.
jmc
--
To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv
next prev parent reply other threads:[~2010-05-11 9:57 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-05-11 11:52 Ulrich Spörlein
2010-05-11 13:45 ` Jason McIntyre [this message]
2010-05-11 14:57 ` Ulrich Spörlein
2010-05-11 15:43 ` Jason McIntyre
2010-05-11 16:23 ` Ulrich Spörlein
2010-05-11 20:09 ` Kristaps Dzonsons
2010-05-11 20:27 ` Ulrich Spörlein
2010-05-11 20:59 ` Jason McIntyre
2010-05-12 12:50 ` Kristaps Dzonsons
2010-05-13 22:23 ` Thomas Klausner
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20100511134542.GA24992@bramka.kerhand.co.uk \
--to=jmc@kerhand.co.uk \
--cc=discuss@mdocml.bsd.lv \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).