[pacman-dev] asciidoc

[Andrew Fyfe]

Dan McGee wrote:
> On 7/6/07, Andrew Fyfe <andrew at neptune-one.net> wrote:
>> Dan McGee wrote:
>>> On 7/2/07, Andrew Fyfe <andrew at neptune-one.net> wrote:
>>>> Dan McGee wrote:
>>>>  > -Dan
>>>>  >
>>>>  > PS Did you see my asciidoc branch? It should be ready for any more
>>>>  > manpages you have up your sleeve.
>>>>
>>>>
>>>> I've rebased my asciidoc branch off of your's Dan and added the rest of
>>>> the man pages. There's still some format tweaks required.
>>> Looking good so far. A few things of note:
>>> 1. We should probably make doc/ generation 'optional' in the sense
>>> that we ship with premade manpages but users can still regenerate them
>>> on their own. This way they are not required to have the whole
>>> asciidoc toolchain. (Note to self: move asciidoc into extra.)
>> Yes the release tarballs should contain pre-generated man pages and
>> maybe html versions (and Doxygen?)
>>
>>> 2. Guessing you haven't ran a make yet- it fails on a few of our
>>> manpages, those that do not contain a SYNOPSIS section. Any way to get
>>> around this? Manpages in section 5 shouldn't require this (a quick
>>> glance at a few don't have it).
>> Forgot to mention I've patched my copy of asciidoc so it doesn't require
>> a SYNOPSIS section.
>>
>>> At the very least we can keep this as a side branch for a while, and
>>> worry about doing the merge later once we have everything looking
>>> pretty. These will be much easier to maintain than the old ones
>> I need to sit down and go through each page and sort out the formatting
>> issues, I know there's a problem with white space after indented blocks
>> and 2nd level definition lists aren't working.
>>
>>> though, and we should be able to get some pretty-looking HTML as well.
>> HTML pages can be generated by switching one or to options to asciidoc.
>>
>> Andrew
>>
>> diff -Naur asciidoc-8.2.1-orig/asciidoc.py asciidoc-8.2.1/asciidoc.py
>> --- asciidoc-8.2.1-orig/asciidoc.py     2007-04-04 23:09:06.000000000 +0100
>> +++ asciidoc-8.2.1/asciidoc.py  2007-06-02 15:43:17.000000000 +0100
>> @@ -1203,23 +1203,23 @@
>>                      writer.write(stag)
>>                      Section.translate_body()
>>                      writer.write(etag)
>> -            else:
>> -                # Translate manpage SYNOPSIS.
>> -                if Lex.next() is not Title:
>> -                    error('SYNOPSIS section expected')
>> -                else:
>> -                    Title.translate()
>> -                    if string.upper(Title.dict['title']) <> 'SYNOPSIS':
>> -                        error('second section must be named SYNOPSIS')
>> -                    if Title.level != 1:
>> -                        error('SYNOPSIS section title must be at level 1')
>> -                    d = {}
>> -                    d.update(Title.dict)
>> -                    AttributeList.consume(d)
>> -                    stag,etag = config.section2tags('sect-synopsis',d)
>> -                    writer.write(stag)
>> -                    Section.translate_body()
>> -                    writer.write(etag)
>> +            #else:
>> +            #    # Translate manpage SYNOPSIS.
>> +            #    if Lex.next() is not Title:
>> +            #        error('SYNOPSIS section expected')
>> +            #    else:
>> +            #        Title.translate()
>> +            #        if string.upper(Title.dict['title']) <> 'SYNOPSIS':
>> +            #            error('second section must be named SYNOPSIS')
>> +            #        if Title.level != 1:
>> +            #            error('SYNOPSIS section title must be at level 1')
>> +            #        d = {}
>> +            #        d.update(Title.dict)
>> +            #        AttributeList.consume(d)
>> +            #        stag,etag = config.section2tags('sect-synopsis',d)
>> +            #        writer.write(stag)
>> +            #        Section.translate_body()
>> +            #        writer.write(etag)
>>          else:
>>              if config.header_footer:
>>                  hdr = config.subs_section('header',{})
> 
> Is there anyway we can get some "fix" made in asciidoc upstream? This
> is not the kind of hack I want. Some option like "--no-section-check"
> or something would be nice. At the very least, we could do what the
> section 5 git manpages do (man 5 gitattribute, gitignore, gitmodules).
> 
> I have all of our stuff on my updated asciidoc branch, if you want to
> base your work off there. (git-cherry-pick is the helpful command of
> the day, by the way.)
> 
> -Dan
> 
> _______________________________________________
> pacman-dev mailing list
> pacman-dev at archlinux.org
> http://archlinux.org/mailman/listinfo/pacman-dev

Ok I've copied git and added a Synopsis section to the man 5 pages, Can 
you repull "Convert the remaining man pages to asciidoc." patch, you 
must have pulled it before I fixed the whitespace*.

Andrew

* vim doesn't like PKGBUILD.5.txt it keeps getting the file type wrong 
and screwing up the white space.