[augeas-devel] Re: NaturalDocs & Augeas

[Raphaël Pinson]

I revamped the CSS a bit (the --style option is very useful) and added some
comments to the modules (not sure about using "About: Lens Usage" instead of
"Sample Usage:", but "Sample Usage" didn't integrate as nicely in the page):


http://r.pinson.free.fr/augeas/doc/files/sudoers-aug.html


Raphael



On Sat, Sep 6, 2008 at 1:02 AM, Raphaël Pinson <raphink at gmail.com> wrote:

>
>
> On Sat, Sep 6, 2008 at 12:43 AM, Greg Valure <gregvalure at naturaldocs.org>wrote:
>
>>  Raphaël Pinson wrote:
>>
>>
>>
>> On Fri, Sep 5, 2008 at 11:39 PM, Raphaël Pinson <raphink at gmail.com>wrote:
>>
>>>
>>>
>>>  On Fri, Sep 5, 2008 at 11:32 PM, Raphaël Pinson <raphink at gmail.com>wrote:
>>>
>>>> Thank you for the quick answer!
>>>>
>>>> I haven't had the time to try your changed yet, but I'm looking forward
>>>> to it.
>>>>
>>>>
>>>>  On Fri, Sep 5, 2008 at 7:22 PM, Greg Valure <
>>>> gregvalure at naturaldocs.org> wrote:
>>>>
>>>>> First replace Topics.txt with this one.  You don't want the variable
>>>>> and lens types to always be global, they should inherit their scope from the
>>>>> module topic.  See here for more information about scope:
>>>>>
>>>>> http://www.naturaldocs.org/customizingtopics.html
>>>>>
>>>>> Next replace Languages.txt with this one.  It adds prototype detection
>>>>> using line breaks and "let" keywords to end them, and tells it to look for a
>>>>> Perl module for some fine tuning.  See here for more information on
>>>>> prototype detection:
>>>>>
>>>>> http://www.naturaldocs.org/customizinglanguages.html
>>>>>
>>>>> Add Augeas.pm to the [ND Dir]/Modules/NaturalDocs/Languages folder.
>>>>>  Edit [ND Dir]/Modules/NaturalDocs/Languages.pm to add "use
>>>>> NaturalDocs::Languages::Augeas" after all the rest.  From what I can tell
>>>>> from the code a declaration continues until the next "let" or the end of the
>>>>> file rather than having a set token.  This Perl module tells it to accept a
>>>>> line break as a prototype ender but keep looking, so if the code gets cut
>>>>> off by another comment it will still be accepted, and also accept "let" as
>>>>> long as it's not the first one, so if another statement appears it
>>>>> definitely ends but it doesn't get tripped up on its own "let".
>>>>>
>>>>
>>>> That's the basic scheme indeed, with a few other keywords and
>>>> specificitiesm like
>>>>
>>>> * you can have local variables, like
>>>>
>>>> let var =
>>>>     let local = some value in
>>>>        some other value using local
>>>>
>>>> * you can have tests, introduced by the keyword "test"
>>>>
>>>> * you can have modules, introduced by the keyword "module", only one
>>>> module per file, at the beginning of the file
>>>>
>>>> * you can have filters, introduced by the keyword "filter"
>>>> So far, only modules and variables ("let" statements) are interesting to
>>>> document.
>>>>
>>>
>>>
>>> Also, variables can have parameters, with mandatory types, like:
>>>
>>> let some_var (name:string) (kw:regexp) (entry:lens) =
>>>      some expression using the parameters
>>>
>>> parameters can be typed as string, regexp or lens.
>>>
>>> Lenses are variables that either use [ ]  in their definition, or refer
>>> to a variable which is a lens. This is a major concept in augeas, and it's
>>> somehow useful to make the difference between simple variables and lenses
>>> (which you find in the code I sent you).
>>>
>>>
>>
>> Oh, and last, but not least... You probably noticed that we use references
>> like Util.eol, so "." is used as a package separator (if I'm not wrong on
>> the wording). Is that specified by adding a "Package Separator" field to the
>> "Augeas Module" definition? And if so, will it append the module name with a
>> dot before every variable automatically?
>>
>>
>>  Raphael
>>
>>
>> Here's an updated Augeas.pm and Languages.txt which handles the "let x =
>> let y = ..." scenario.  It will ignore the "let" as an ender if it's
>> immediately preceded by an equals sign.  Lenses or variables with parameters
>> don't look like it would trip it up.
>>
>> The package separator defaults to "." when you don't specify it, so you
>> don't have to worry there.  It won't show the the variables as "Util.eol" in
>> the title but it knows that's what they are internally so you can still link
>> to them that way.  That's what the module's scope was for, and why you don't
>> want to break it with Section or Title tags.
>>
>
>
> I just tried it. It works great, thank you so much.
>
>
>
> And I'm apparently not allowed to post to that mailing list you CC'd, so if
>> you want them to know about my responses you'll have to post them yourself.
>
>
> Yes, they will see the answer  quoted in my replies, it's ok.
>
>
> Thank you for your help and patience :)
>
>
> Raphael
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/augeas-devel/attachments/20080906/80f09c50/attachment.htm>