Re: mdoc section ordering

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

[-- 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()