[pacman-dev] asciidoc

[Dan McGee]

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