[augeas-devel] Re: NaturalDocs & Augeas
Raphaël Pinson
raphink at gmail.com
Fri Sep 5 21:32:58 UTC 2008
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.
>
> Next you have to change the way you document. Stop using Title and Section
> keywords as they make everything under it global, breaking the scope you
> want from the modules. Use Group instead. Second, document everything over
> its individual element and without manually adding the scope to the title.
Ah, good to know, thank you :)
> So this:
>
> (* Group: Separators
>
> Variable: OpenVPN.sep
> Space separator, inherited from <Util.del_ws_spc>
>
> Definition:
> > Util.del_ws_spc
>
> Variable: OpenVPN.sep_dquote
> Double quote separator
>
> Definition:
> > Util.del_str "\""
> *)
>
> let sep = Util.del_ws_spc
> let sep_dquote = Util.del_str "\""
> Becomes this:
>
> (* Group: Separators
>
> Variable: sep
> Space separator, inherited from <Util.del_ws_spc>
> *)
> let sep = Util.del_ws_spc
>
> (* Variable: sep_dquote
> Double quote separator
> *)
> let sep_dquote = Util.del_str "\""
>
> This code will unfortunately not work in 2.0 because it's going to have a
> completely different way of working internally and will not be using Perl at
> all.
>
So what is best? Is there a usable beta version of 2.0 yet, so we could use
it already, or should begin to use 1.4 and then migrate to 2.0, and how
hard will that be?
Regards,
Raphael
>
>
> Raphaël Pinson wrote:
>
>> Hello,
>>
>>
>> I have begun to use NaturalDocs to document modules written in the Augeas
>> language [0]. First let me tell you that NaturalDocs is a great help to
>> easily set documentation without having to write a parser. This is a
>> wonderful project and we are very thankful for it.
>>
>> For now, I have done very basic settings on NaturalDocs to enable it for
>> Augeas files. You can have a look at the code on [1] and the settings on
>> [2]. As you can see, Augeas uses a kind of ML (ala Ocaml) language which is
>> declarative.
>>
>> Now when I write the doc for a file, I have to repeat the definition of
>> variables instead of parsing them from the code, which would be much more
>> useful, and I have to declare whether a declaration is a lens (I use Define
>> for this, since NaturalDocs doesn't know about lenses, which is quite
>> normal) or a simple variable (I use Variable for that). Lenses are variables
>> that either contain [ ] or reference another lens, which has to be declared
>> beforehand.
>>
>> To the point: I'm wondering where I can find documentation on how to
>> expand NaturalDocs to parse the Augeas code and grab these infos without
>> duplicating them in the comments. I'm also seeing that you're currently
>> porting NaturalDocs to .net/mono and wondering if the Perl modules to expand
>> language support will still work in NaturalDocs 2.0.
>>
>>
>> Regards
>>
>>
>>
>> Raphaël
>>
>>
>> [0] http://augeas.net
>> [1] http://r.pinson.free.fr/augeas/doc/augfiles
>> [2] http://r.pinson.free.fr/augeas/doc/conf
>>
>
>
>
> ###############################################################################
> #
> # Class: NaturalDocs::Languages::Augeas
> #
>
> ###############################################################################
> #
> # A subclass to handle the language variations of Tcl.
> #
>
> ###############################################################################
>
> # This file is part of Natural Docs, which is Copyright (C) 2003-2008 Greg
> Valure
> # Natural Docs is licensed under the GPL
>
> use strict;
> use integer;
>
> package NaturalDocs::Languages::Augeas;
>
> use base 'NaturalDocs::Languages::Simple';
>
>
> my $pastFirstLet;
>
>
> sub OnCode #(...)
> {
> my ($self, @params) = @_;
>
> $pastFirstLet = 0;
>
> return $self->SUPER::OnCode(@params);
> };
>
>
> #
> # Function: OnPrototypeEnd
> #
> # Tcl's function syntax is shown below.
> #
> # > proc [name] { [params] } { [code] }
> #
> # The opening brace is one of the prototype enders. We need to allow the
> first opening brace because it contains the
> # parameters.
> #
> # Also, the parameters may have braces within them. I've seen one that
> used { seconds 20 } as a parameter.
> #
> # Parameters:
> #
> # type - The <TopicType> of the prototype.
> # prototypeRef - A reference to the prototype so far, minus the ender
> in dispute.
> # ender - The ender symbol.
> #
> # Returns:
> #
> # ENDER_ACCEPT - The ender is accepted and the prototype is finished.
> # ENDER_IGNORE - The ender is rejected and parsing should continue.
> Note that the prototype will be rejected as a whole
> # if all enders are ignored before
> reaching the end of the code.
> # ENDER_ACCEPT_AND_CONTINUE - The ender is accepted so the prototype
> may stand as is. However, the prototype might
> # also continue on
> so continue parsing. If there is no accepted ender between here and
> # the end of the
> code this version will be accepted instead.
> # ENDER_REVERT_TO_ACCEPTED - The expedition from
> ENDER_ACCEPT_AND_CONTINUE failed. Use the last accepted
> # version and end
> parsing.
> #
> sub OnPrototypeEnd #(type, prototypeRef, ender)
> {
> my ($self, $type, $prototypeRef, $ender) = @_;
>
> if ($ender eq "\n")
> { return ::ENDER_ACCEPT_AND_CONTINUE(); }
> elsif ($ender eq "let" && !$pastFirstLet)
> {
> $pastFirstLet = 1;
> return ::ENDER_IGNORE();
> }
> else
> { return ::ENDER_ACCEPT(); };
> };
>
>
> 1;
>
> Format: 1.4
>
> # This is the Natural Docs languages file for this project. If you change
> # anything here, it will apply to THIS PROJECT ONLY. If you'd like to
> change
> # something for all your projects, edit the Languages.txt in Natural Docs'
> # Config directory instead.
>
>
> Ignore Extension: pl
>
>
>
> #-------------------------------------------------------------------------------
> # SYNTAX:
> #
> # Unlike other Natural Docs configuration files, in this file all comments
> # MUST be alone on a line. Some languages deal with the # character, so
> you
> # cannot put comments on the same line as content.
> #
> # Also, all lists are separated with spaces, not commas, again because some
> # languages may need to use them.
> #
> # Language: [name]
> # Alter Language: [name]
> # Defines a new language or alters an existing one. Its name can use
> any
> # characters. If any of the properties below have an add/replace form,
> you
> # must use that when using Alter Language.
> #
> # The language Shebang Script is special. It's entry is only used for
> # extensions, and files with those extensions have their shebang (#!)
> lines
> # read to determine the real language of the file. Extensionless files
> are
> # always treated this way.
> #
> # The language Text File is also special. It's treated as one big
> comment
> # so you can put Natural Docs content in them without special symbols.
> Also,
> # if you don't specify a package separator, ignored prefixes, or enum
> value
> # behavior, it will copy those settings from the language that is used
> most
> # in the source tree.
> #
> # Extensions: [extension] [extension] ...
> # [Add/Replace] Extensions: [extension] [extension] ...
> # Defines the file extensions of the language's source files. You can
> # redefine extensions found in the main languages file. You can use *
> to
> # mean any undefined extension.
> #
> # Shebang Strings: [string] [string] ...
> # [Add/Replace] Shebang Strings: [string] [string] ...
> # Defines a list of strings that can appear in the shebang (#!) line to
> # designate that it's part of the language. You can redefine strings
> found
> # in the main languages file.
> #
> # Ignore Prefixes in Index: [prefix] [prefix] ...
> # [Add/Replace] Ignored Prefixes in Index: [prefix] [prefix] ...
> #
> # Ignore [Topic Type] Prefixes in Index: [prefix] [prefix] ...
> # [Add/Replace] Ignored [Topic Type] Prefixes in Index: [prefix] [prefix]
> ...
> # Specifies prefixes that should be ignored when sorting symbols in an
> # index. Can be specified in general or for a specific topic type.
> #
>
> #------------------------------------------------------------------------------
> # For basic language support only:
> #
> # Line Comments: [symbol] [symbol] ...
> # Defines a space-separated list of symbols that are used for line
> comments,
> # if any.
> #
> # Block Comments: [opening sym] [closing sym] [opening sym] [closing sym]
> ...
> # Defines a space-separated list of symbol pairs that are used for block
> # comments, if any.
> #
> # Package Separator: [symbol]
> # Defines the default package separator symbol. The default is a dot.
> #
> # [Topic Type] Prototype Enders: [symbol] [symbol] ...
> # When defined, Natural Docs will attempt to get a prototype from the
> code
> # immediately following the topic type. It stops when it reaches one of
> # these symbols. Use \n for line breaks.
> #
> # Line Extender: [symbol]
> # Defines the symbol that allows a prototype to span multiple lines if
> # normally a line break would end it.
> #
> # Enum Values: [global|under type|under parent]
> # Defines how enum values are referenced. The default is global.
> # global - Values are always global, referenced as 'value'.
> # under type - Values are under the enum type, referenced as
> # 'package.enum.value'.
> # under parent - Values are under the enum's parent, referenced as
> # 'package.value'.
> #
> # Perl Package: [perl package]
> # Specifies the Perl package used to fine-tune the language behavior in
> ways
> # too complex to do in this file.
> #
>
> #------------------------------------------------------------------------------
> # For full language support only:
> #
> # Full Language Support: [perl package]
> # Specifies the Perl package that has the parsing routines necessary for
> full
> # language support.
> #
>
> #-------------------------------------------------------------------------------
>
> # The following languages are defined in the main file, if you'd like to
> alter
> # them:
> #
> # Text File, Shebang Script, C/C++, C#, Java, JavaScript, Perl, Python,
> # PHP, SQL, Visual Basic, Pascal, Assembly, Ada, Tcl, Ruby, Makefile,
> # ActionScript, ColdFusion, R, Fortran
>
> # If you add a language that you think would be useful to other developers
> # and should be included in Natural Docs by default, please e-mail it to
> # languages [at] naturaldocs [dot] org.
>
>
> Language: Augeas
>
> Extension: aug
> Block Comment: (* *)
> AugeasVariable Prototype Enders: \n let
> AugeasLens Prototype Enders: \n let
> AugeasModule Prototype Enders: \n let
> Perl Package: NaturalDocs::Languages::Augeas
>
> Format: 1.4
>
> # This is the Natural Docs topics file for this project. If you change
> anything
> # here, it will apply to THIS PROJECT ONLY. If you'd like to change
> something
> # for all your projects, edit the Topics.txt in Natural Docs' Config
> directory
> # instead.
>
>
> Ignore Keywords:
> class
>
>
>
> #-------------------------------------------------------------------------------
> # SYNTAX:
> #
> # Topic Type: [name]
> # Alter Topic Type: [name]
> # Creates a new topic type or alters one from the main file. Each type
> gets
> # its own index and behavior settings. Its name can have letters,
> numbers,
> # spaces, and these charaters: - / . '
> #
> # Plural: [name]
> # Sets the plural name of the topic type, if different.
> #
> # Keywords:
> # [keyword]
> # [keyword], [plural keyword]
> # ...
> # Defines or adds to the list of keywords for the topic type. They may
> only
> # contain letters, numbers, and spaces and are not case sensitive.
> Plural
> # keywords are used for list topics. You can redefine keywords found in
> the
> # main topics file.
> #
> # Index: [yes|no]
> # Whether the topics get their own index. Defaults to yes. Everything
> is
> # included in the general index regardless of this setting.
> #
> # Scope: [normal|start|end|always global]
> # How the topics affects scope. Defaults to normal.
> # normal - Topics stay within the current scope.
> # start - Topics start a new scope for all the topics beneath
> it,
> # like class topics.
> # end - Topics reset the scope back to global for all the
> topics
> # beneath it.
> # always global - Topics are defined as global, but do not change the
> scope
> # for any other topics.
> #
> # Class Hierarchy: [yes|no]
> # Whether the topics are part of the class hierarchy. Defaults to no.
> #
> # Page Title If First: [yes|no]
> # Whether the topic's title becomes the page title if it's the first one
> in
> # a file. Defaults to no.
> #
> # Break Lists: [yes|no]
> # Whether list topics should be broken into individual topics in the
> output.
> # Defaults to no.
> #
> # Can Group With: [type], [type], ...
> # Defines a list of topic types that this one can possibly be grouped
> with.
> # Defaults to none.
>
> #-------------------------------------------------------------------------------
>
> # The following topics are defined in the main file, if you'd like to alter
> # their behavior or add keywords:
> #
> # Generic, Class, Interface, Section, File, Group, Function, Variable,
> # Property, Type, Constant, Enumeration, Event, Delegate, Macro,
> # Database, Database Table, Database View, Database Index, Database
> # Cursor, Database Trigger, Cookie, Build Target
>
> # If you add something that you think would be useful to other developers
> # and should be included in Natural Docs by default, please e-mail it to
> # topics [at] naturaldocs [dot] org.
>
>
> Topic Type: AugeasLens
>
> Plural: Augeas Lenses
> Keywords:
> define, defines
>
>
> Topic Type: AugeasVariable
>
> Plural: Augeas Variables
> Keywords:
> variable, variables
>
>
> Topic Type: AugeasModule
>
> Plural: Augeas Modules
> Scope: Start
> Page Title If First: Yes
>
> Keywords:
> module, modules
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/augeas-devel/attachments/20080905/0cdd0d31/attachment.htm>
More information about the augeas-devel
mailing list