[augeas-devel] Re: NaturalDocs & Augeas

[Raphaël Pinson]

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/b792d5d8/attachment.htm>