mdoc section ordering

mdoc section ordering

[Ulrich Spörlein]

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
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: mdoc section ordering

[Jason McIntyre]

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

Re: mdoc section ordering

[Ulrich Spörlein]

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

Re: mdoc section ordering

[Jason McIntyre]

On Tue, May 11, 2010 at 04:57:11PM +0200, Ulrich Sp??rlein wrote:
> 
> 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.
> 

ah, sorry, i misunderstood then. so yeah, it makes no difference to us.

> 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.
> 

as far as i know, EXIT STATUS is not even a standard section header. for
example, the groff_mdoc.7 page that comes with the latest groff does not
list it. so maybe there is no issue, and you shouldn;t worry about where
it's put?

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

Re: mdoc section ordering

[Ulrich Spörlein]

On Tue, 11.05.2010 at 16:42:53 +0059, Jason McIntyre wrote:
> On Tue, May 11, 2010 at 04:57:11PM +0200, Ulrich Sp??rlein wrote:
> > 
> > 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.
> > 
> 
> ah, sorry, i misunderstood then. so yeah, it makes no difference to us.
> 
> > 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.
> > 
> 
> as far as i know, EXIT STATUS is not even a standard section header. for
> example, the groff_mdoc.7 page that comes with the latest groff does not
> list it. so maybe there is no issue, and you shouldn;t worry about where
> it's put?

I'm fine with that, only then mandoc should stop "enforcing" this
ordering. It's perfectly fine with me!

Kristaps, what to you think?

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

Re: mdoc section ordering

[Kristaps Dzonsons]

> I'm fine with that, only then mandoc should stop "enforcing" this
> ordering. It's perfectly fine with me!
> 
> Kristaps, what to you think?

Seems the consensus is to roll with the FreeBSD version, which is fine 
by me.  The sections were originally unioned over all mdoc.template and 
man.template files I could find.  I didn't sweat the order.

End result:

.Sh NAME
.Sh LIBRARY
.Sh SYNOPSIS
.Sh DESCRIPTION
.Sh IMPLEMENTATION NOTES  <-- this one seems wankiest to me
.Sh RETURN VALUES
.Sh ENVIRONMENT
.Sh FILES
.Sh EXIT STATUS
.Sh EXAMPLES
.Sh DIAGNOSTICS
.Sh COMPATIBILITY
.Sh ERRORS
.Sh SEE ALSO
.Sh STANDARDS
.Sh HISTORY
.Sh AUTHORS
.Sh CAVEATS
.Sh BUGS
.Sh SECURITY CONSIDERATIONS  <-- shouldn't this be CAVEATS?

Jason, in my opinion, COMPATIBILITY and STANDARDS shouldn't be merged in 
all cases.  Take mdocml's man.7 and mdoc.7, for example: the 
COMPATIBILITY section is used to enumerate the differences between 
troffs and mandoc.  Since -man, -mdoc, etc. aren't standards, where else 
would this go?

Anyway, if everybody ok's this order, I'll commit it and add the 
requisite bits to the docs.

Ulrich, you said you know of a handful of mis-ordered NetBSD pages.  Can 
you post those to Joerg?  He'll probably want to know about them (will 
your python script auto-gen a patch for him?).

Thanks,

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

Re: mdoc section ordering

[Ulrich Spörlein]

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

On Tue, 11.05.2010 at 22:09:49 +0200, Kristaps Dzonsons wrote:
> > I'm fine with that, only then mandoc should stop "enforcing" this
> > ordering. It's perfectly fine with me!
> > 
> > Kristaps, what to you think?
> 
> Seems the consensus is to roll with the FreeBSD version, which is fine 
> by me.  The sections were originally unioned over all mdoc.template and 
> man.template files I could find.  I didn't sweat the order.
> 
> End result:
> 
> .Sh NAME
> .Sh LIBRARY
> .Sh SYNOPSIS
> .Sh DESCRIPTION
> .Sh IMPLEMENTATION NOTES  <-- this one seems wankiest to me
> .Sh RETURN VALUES
> .Sh ENVIRONMENT
> .Sh FILES
> .Sh EXIT STATUS
> .Sh EXAMPLES
> .Sh DIAGNOSTICS
> .Sh COMPATIBILITY
> .Sh ERRORS
> .Sh SEE ALSO
> .Sh STANDARDS
> .Sh HISTORY
> .Sh AUTHORS
> .Sh CAVEATS
> .Sh BUGS
> .Sh SECURITY CONSIDERATIONS  <-- shouldn't this be CAVEATS?
> 
> Jason, in my opinion, COMPATIBILITY and STANDARDS shouldn't be merged in 
> all cases.  Take mdocml's man.7 and mdoc.7, for example: the 
> COMPATIBILITY section is used to enumerate the differences between 
> troffs and mandoc.  Since -man, -mdoc, etc. aren't standards, where else 
> would this go?
> 
> Anyway, if everybody ok's this order, I'll commit it and add the 
> requisite bits to the docs.
> 
> Ulrich, you said you know of a handful of mis-ordered NetBSD pages.  Can 
> you post those to Joerg?  He'll probably want to know about them (will 
> your python script auto-gen a patch for him?).

The script is by Ruslan, not me. I actually did the reordering by hand
using vim macros, but if my understanding of python is correct it will
print out re-ordered manpages which should be very useful.

I'm sure Ruslan wouldn't mind me posting the script for general use.
Make sure you update the section ordering to what you want to end up
with.

Uli

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

#!/usr/local/bin/python
# -*- coding: KOI8-R -*-

import sys

sections = [
    '00',
    'NAME', 'НАЗВАНИЕ',
    'LIBRARY', 'БИБЛИОТЕКА',
    'SYNOPSIS', 'СИНТАКСИС',
    'DESCRIPTION', 'ОПИСАНИЕ',
    'IMPLEMENTATION NOTES', 'ОСОБЕННОСТИ РЕАЛИЗАЦИИ',
    'RETURN VALUES', 'ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ',
    'ENVIRONMENT', 'ОКРУЖЕНИЕ',
    'FILES', 'ФАЙЛЫ',
    'EXIT STATUS', 'СТАТУС ЗАВЕРШЕНИЯ',
    'EXAMPLES', 'ПРИМЕРЫ',
    'DIAGNOSTICS', 'ДИАГНОСТИКА',
    'COMPATIBILITY', 'СОВМЕСТИМОСТЬ',
    'ERRORS', 'ОШИБКИ',
    'SEE ALSO', 'СМОТРИ ТАКЖЕ',
    'STANDARDS', 'СТАНДАРТЫ',
    'HISTORY', 'ИСТОРИЯ',
    'AUTHORS', 'АВТОРЫ',
    'BUGS', 'ПРОБЛЕМЫ',
]

def check_sections(manpage):
    lines = {}
    section = '00'
    last_idx = 0
    lineno = 0
    for line in file(manpage):
        lineno += 1
        words = line.split()
        if len(words) > 0 and words[0] == '.Sh':
            sname = ' '.join(words[1:])
            if (sname in sections):
                idx = sections.index(sname)
                if (idx < last_idx):
                    warn("%s:%d: %s comes before %s" % (manpage, lineno, sname, sections[last_idx]))
                last_idx = idx
                section = sname
        if section not in lines:
            lines[section] = []
        lines[section].append(line)
    for section in sections:
        if section in lines:
            for line in lines[section]:
                print line,

def warn(msg):
    sys.stderr.write(msg + '\n')

def main():
    if len(sys.argv) > 1:
        for file in sys.argv[1:]:
            check_sections(file)
    else:
        check_sections("/dev/stdin")

main()

Re: mdoc section ordering

[Jason McIntyre]

On Tue, May 11, 2010 at 10:09:49PM +0200, Kristaps Dzonsons wrote:
> 
> Jason, in my opinion, COMPATIBILITY and STANDARDS shouldn't be merged in 
> all cases.  Take mdocml's man.7 and mdoc.7, for example: the 
> COMPATIBILITY section is used to enumerate the differences between 
> troffs and mandoc.  Since -man, -mdoc, etc. aren't standards, where else 
> would this go?
> 

a separate section sometimes makes sense, yes. but for the general case,
we found it didn;t warrant the need for an "official" section.

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

Re: mdoc section ordering

[Kristaps Dzonsons]

>> Jason, in my opinion, COMPATIBILITY and STANDARDS shouldn't be merged in 
>> all cases.  Take mdocml's man.7 and mdoc.7, for example: the 
>> COMPATIBILITY section is used to enumerate the differences between 
>> troffs and mandoc.  Since -man, -mdoc, etc. aren't standards, where else 
>> would this go?
>>
> 
> a separate section sometimes makes sense, yes. but for the general case,
> we found it didn;t warrant the need for an "official" section.

This has been checked in along with some other bits.  Thanks!

Note that -man doesn't check against sections, largely because I don't
want to bloat the codebase with validating that obsolete shit.
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: mdoc section ordering

[Thomas Klausner]

On Tue, May 11, 2010 at 10:09:49PM +0200, Kristaps Dzonsons wrote:
> End result:
> 
> .Sh NAME
> .Sh LIBRARY
> .Sh SYNOPSIS
> .Sh DESCRIPTION
> .Sh IMPLEMENTATION NOTES  <-- this one seems wankiest to me
> .Sh RETURN VALUES
> .Sh ENVIRONMENT
> .Sh FILES
> .Sh EXIT STATUS
> .Sh EXAMPLES
> .Sh DIAGNOSTICS
> .Sh COMPATIBILITY
> .Sh ERRORS
> .Sh SEE ALSO
> .Sh STANDARDS
> .Sh HISTORY
> .Sh AUTHORS
> .Sh CAVEATS
> .Sh BUGS
> .Sh SECURITY CONSIDERATIONS  <-- shouldn't this be CAVEATS?

The order that's hardcoded in mdoclint (used for checking man pages,
not only for the section order, by jmc@openbsd and myself) is

.Sh NAME
.Sh LIBRARY
.Sh SYNOPSIS
.Sh DESCRIPTION
.Sh EXIT STATUS /* NetBSD only */
.Sh RETURN VALUES
.Sh ENVIRONMENT
.Sh FILES
.Sh EXAMPLES
.Sh DIAGNOSTICS
.Sh ERRORS
.Sh SEE ALSO
.Sh STANDARDS
.Sh HISTORY
.Sh AUTHORS
.Sh CAVEATS
.Sh BUGS
.Sh SECURITY CONSIDERATIONS /* NetBSD only */

i.e. EXIT STATUS is seen as an alternate to RETURN VALUES and put next
to that; and COMPATIBILITY and IMPLEMENTATION NOTES are not defined as
standard sections.

Except for EXIT STATUS, the proposed order is fine with me; not sure
if we should define the COMPATIBILITY and IMPLEMENTATION NOTES as
standard or not, but I don't really care. We'll probably have to fix
some man pages for the order in that case, but that's fine with me.
 Thomas
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv