Re: [gentoo-dev] Gentoo beeping at me!

[Dan Meltzer]

Id prefer to see something like 
#///
#/
#/
#/
#///

that is, each line that goes into documenetation has a prepending
character, so that It is easy to tell it apart without folding,

then again, maybe it doesnt need to be told apart...

or a more in depth one, something like
#///<documentation>
#///<feature>
#///<name>feature name</name>
#///<description>a short description of the problem</description>
#///<paramater>a paramater that could be passed to it</parameter>
#///</feature>
#///<feature>
same as before...
#///</docuementation>

that way all documentation can just be extracted as xml... making
parsing to a web page, or a man page, or whatever, a lot easier IMO

(yes, this was stolen shamelessly from .net's documentation standards :))


On Sat, 27 Nov 2004 03:03:52 +0900, Georgi Georgiev <chutz@×××.net> wrote:
> maillog: 26/11/2004-10:17:34(+0000): Ciaran McCreesh types
>
>
> > On Fri, 26 Nov 2004 11:25:10 +0900 Georgi Georgiev <chutz@×××.net>
> > wrote:
> > | maillog: 25/11/2004-19:19:27(+0000): Ed Grimm types
> > | > On Thu, 25 Nov 2004, Georgi Georgiev wrote:
> > | >
> > | > If you really think that in-line docs are ugly, use vim(1), and
> > | > automagically fold them out of your view (:help foldexpr, although
> > | > this can be set to happen in the eclass syntax file).  I suspect
> > | > that most of the people who only occasionally work with the
> > | > eclasses, and those who are just starting to use the eclasses, would
> > | > find them more useful than ugly.
> > |
> > | I have nothing against in-line docs in general. I simply had trouble
> > | imagining it in the bash case.
> > |
> > | What about using perldoc itself? Simply prepend every doc line with a
> > | '#', then run
> > |
> > | awk '/^#/ { sub("#",""); print }
> >
> > In bash? How would that work?
>
> I imagined
>
> #=item blah blah
> # more POD
> # and more
> # and more
> #=cut
>
> > Here's another possibility:
> >
> > # {{{ doc
> > # whatever format we decide upon
> > # blah blah blah
> > # }}}
> >
> > Doesn't screw up normal comments, really easy to find and process, easy
> > to turn into folds in the editor :)
>
> Sounds great. Now all that's left is to agree upon the format and write
> the converter. Oh, and my favorite -- a GLEP maybe? (no, I'm not
> sarcastic; just in a good mood ;) ).
>
> --
>  )   Georgi Georgiev    ) Hi! I'm Larry. This is my brother Bob, and    )
> (     chutz@×××.net    (  this is my other brother Jimbo. We thought   (
>  )  [phone]    ) you might like to know the names of your      )
> (  ------------------- (  assailants.                                  (
>
>
>

--
gentoo-dev@g.o mailing list