[augeas-devel] [PATCH] Add naturaldocs support

[Raphaël Pinson]

On Sun, Sep 14, 2008 at 12:23 AM, David Lutterkort <lutter at redhat.com>wrote:

> On Sat, 2008-09-13 at 10:54 +0200, Raphaël Pinson wrote:
> >
> >
> > On Sat, Sep 13, 2008 at 2:38 AM, David Lutterkort <lutter at redhat.com>
> > wrote:
> >         On Fri, 2008-09-12 at 16:38 -0700, David Lutterkort wrote:
> >         > Now I just need to figure out how that should appear on the
> >         website ;)
> >
> >
> >         To get something up on the site, I linked the docs from the
> >         'Documentation' section[1]
> >
> >
> > That looks very nice :)
> > In the API documentation, there should be a way to change the title of
> > the pages for the files (it says
> > "/home/lutter/code/augeas/src/augeas.h"). That's a detail though.
>
> Haven't even noticed that - but yeah, that should change.
>

The problem here is that in lenses, there is a module declaration that makes
a title for the whole file, but there is no equivalent to that for the .h
files. So in order to force the title, you could add "Title: Public API" to
the very top of augeas.h.



>
> > Also, I wonder if it would be nice to add the links to the main
> > website like I did in the beginning, or if it would just make it
> > heavier...
>
> Yes, we definitely need backlinks. But I think rather than show the
> whole menu from the main site, we should just have one or two links: one
> to the main site, and one to the Documentation section on the main site.
>
> I think the whole menu will be too heavy.
>

OK, then we can add this to both Menu.txt files. The format would be
something like

Group: Main Links {
   Link: Main (http://augeas.net)
   Link: Documentation (http://augeas.net/doc)
}



>
> > Another thought: now that we separate the C API from the lenses for
> > documentation, there is no need to use "view" to declare lenses since
> > it won't conflict with C declarations. Do you think "view" is a good
> > keyword for it, or rather "define", or something else [0]?
>
> Yeah, I would either make that 'Define' or 'Lens'; I don't think that
> using 'View' there is all that clear.


Then I'm for going back to 'define', since 'lens' is not a valid keyword in
ND.
Btw, ND also allows to declare several objects at the same time with e.g.

Variables: Useful primitives
   eol         - end of line, based on <Util.eol>
   indent     - indentation , based on <Util.indent>
   sep_spc - space separator

This way, all three variables get declared in one shot, but there definition
(code in box) is not added. However, they can still be refered to by other
declarations. This can typically be useful for basic primitives, like 'let
eol = Util.eol'.



Raphael
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/augeas-devel/attachments/20080914/512ce690/attachment.htm>