[pacman-dev] asciidoc

[Dan McGee]

On 7/6/07, Andrew Fyfe <andrew at neptune-one.net> wrote:
> 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.

Looks like you forgot to add PKGBUILD-example.txt to the mix. While
you are at it, you should add this rule too to the makefile:

PKGBUILD.5: PKGBUILD-example.txt

right under the footer.txt rule or something. I assume I am going to
get stuck doing the autoconf goodness as well (things like checking
for asciidoc, making the doc/ target optional, etc.).

-Dan