[prev in list] [next in list] [prev in thread] [next in thread] 

List:       busybox
Subject:    Re: what's the proper format for include/usage.h to not mangle output?
From:       "Robert P. J. Day" <rpjday () crashcourse ! ca>
Date:       2008-12-26 10:35:59
Message-ID: alpine.LFD.2.00.0812260533240.29026 () localhost ! localdomain
[Download RAW message or body]

On Thu, 25 Dec 2008, Denys Vlasenko wrote:

> On Thursday 25 December 2008 11:36, Robert P. J. Day wrote:
> >
> >   i've been refreshing my memory on the usage of a number of BB
> > applets, and it's obvious that the format of the usage.h file lends
> > itself to some mangled output in terms of HTML.
> >
> >   as i read it, defining the trivial usage of an applet is simple as
> > long as there's a single line of trivial usage -- the "make doc"
> > processing step adds the name of the applet in front of the trivial
> > usage string and you get what you see for, as an example, "addgroup":
> >
> >   http://busybox.net/downloads/BusyBox.html
> >
> > but that's when things start to fall apart.
> >
> >   if you want multiple trivial usage strings, you apparently need to
> > get a bit hacky, as you can see for "arp", which prints the command
> > string "arp", then apparently requires usage.h to include the multiple
> > strings all below, prefixed with "\n".  fair enough, but that's not
> > compatible with the way, say, "chcon" is explained in the usage.h
> > file:
> >
> > #define chcon_trivial_usage \
> >        "[OPTIONS] CONTEXT FILE..." \
> >        "\n      chcon [OPTIONS] [-u USER] [-r ROLE] [-l RANGE] [-t TYPE] FILE..." \
> >         USE_FEATURE_CHCON_LONG_OPTIONS( \
> >        "\n      chcon [OPTIONS] --reference=RFILE FILE..." \
> >         )
> >
> > as you can see, whoever wrote the usage for "chcon" decided to (as
> > opposed to "arp") sneak in the "chcon" command name on each line, but
> > the HTML output is definitely not normal, as you can see at the web
> > page.
> >
> >   so what's the standard for the above?  other commands don't come off
> > well in terms of HTML:  chpst, dd and so on.  is there a proper way to
> > represent all of that so that the HTML looks sane?
>
> I think it makes sense to:
>
> 1. Investigate all broken cases and fix them one way or another.
> 2. Add comment to the top of usage.h explaining the rules
>    ("HOWTO write helptext so that it doesn't break .html")
> 3. Package it all as a .patch file and mail to the list.

  i agree, but the trick is to decide what the standard is going to
be.  you can't fix breakage until you can define *precisely* just how
something is broken.

  if i get a few minutes later, i'll try to be more specific about
what i'm trying to do.

rday
--

========================================================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry:
    Have classroom, will lecture.

http://crashcourse.ca                          Waterloo, Ontario, CANADA
========================================================================
_______________________________________________
busybox mailing list
busybox@busybox.net
http://lists.busybox.net/mailman/listinfo/busybox
[prev in list] [next in list] [prev in thread] [next in thread]