[Doxygen-develop] TO-DO item 10 and suggestions for @import/@region/@endregion

[Dan L. <dl...@he...>]

Dear List:

Citation of TO-DO list item 10 regarding proposed
@import/@region/@endregion command suite followed by my suggestions:

---------------
Requested by Erik Johannes: 
The ability to include a block of text from a file. This should not
always be all the contents of the file, but instead a specific region
from the file. 

Suggested are the following tags: 

    @import <file> [region-tag]

Imports the contents of the file in to the current stream of processing.
The imported text is treated as if it had been located at the site of
importation. If the optional [region-tag] is specified, then only those
regions in the file being imported that have the specified [region-tag]
will be imported.
All other contents of the imported file will be ignored. 

    @region <region-tag> [skip-lines]

Specifies the beginning of a region that can be imported into the
processing stream of another file using the import command. The
importation will begin at the line following the line the region command
is found on. The optional [skip-lines] parameter can be used to specify
that the next n lines following the line containing the region command
should not be imported. Importation will continue until an endregion for
the specified tag is found or the end of file is reached.

The importation is verbatim with the exception of an other embedded
region/endregion lines within the region block being imported. Those
embedded region/endregion lines will be excluded from the importation. 

    @endregion <region-tag>

Ends the current named region specified by the tag. 

---------------

My comments:

I was introduced about 5 years ago to Doxygen and have used it in a
number of projects.  I am currently involved in one which could make
effective use of the @import/@region/@endregion commands as suggested
above.

What would it take to implement the suite of @import/@region/@endregion
keywords?  What area of the code need modification?  I am currently
examining the 1.5.6 source code and see the lexeme parsing in
'src/scanner.l' but there appears to be quite a number of intergrated
components that support specific language parsers as well.  Would this
feature be only concerned with 'src/scanner.l' or would there be
additional areas needing modification?  It appeared on first glance like
the following files also might
participate:

    doc/commands.doc

    src/cmdmapper.cpp
    src/commentscan.l
    src/compound.xsd
    src/compound_xsd.h
    src/docparser.{cpp|h"
    src/docparser.{cpp|h}
    src/{html|latex|man|rtfdoc|xml}visitor.{cpp|h}

    addon/doxmlparser/include/doxmlintf.h
    addon/doxmlparser/src/dochandler.{cpp|h}
    addon/doxmlparser/src/doxmlintf.h
    addon/doxmlparser/test/main.cpp

I am sure this is only a partial an probably inaccurate list.

If I were to use these keywords, I would suggest that a list of regions
be specified, so instead of @e only an optional @e single region tag to
be imported,

    @import <file> [region_tag]

I might suggest a list of them,

    @import <file> [region_tag1 [, region_tag2...]]

suggesting commas as a delimter only since I am not @e intimately
familiar with the nuances of all Doxygen particulars.  (Perhaps white
space alone would be enough?)  However, a series of @import lines could
work just fine as well,

    @import <file> region_tag1
    @import <file> region_tag2
    ...

I think the exclusion of embedded @region and @endregion tags embedded
within a @region/@endregion pair is the right thing to do.  Also, I
would assume that any embedded @import statements would be processed
like any other tag?

Another possibility for something that is @e similar to
@import/@region/@endregion might be to modify the @copydoc tag, which
currently is defined as,

    @copydoc <link-object>

Perhaps two modifications to this
tag would be useful.  The first would
perform something similar to the
TO-DO item 10 using @import/@region/@endregion but might be simpler to
implement since it would use @e only existing structures:

    @copydoc <link-object> [section-name-1 [, section-name-2 [...]]

This would perform an @import of one or more named sections.  A related
idea might be to use this syntax to import one or more named sections or
pages instead, this time using the same idea as @copybrief and
@copydetails (BTW, the @copydoc reference to those items say
"\cmdcopybrief" and "\cmdcopydetails"
instead of "\copybrief" and "\copydetails", respectively).
These might look like,

    @copysection section-name-1 [, section-name-2 [...]]

    @copypage page-name-1 [, page-name-2 [...]]

Would these ideas help perform a simpler @import at the expense of being
less generic?  I think they might work because if text is already
organized into @page and @section logically, perhaps this might fill in
much of a completely generic @import.

<b>ON THE OTHER HAND</b>, an @import/@region/@endregion suite of
commands is @e not bound to any particular of @page or @section
organization.  It might be a second step in implementing a @copyXXX
modification above.  It also might be considered more generic to have a
"label"
for a sub-region as well as or perhaps instead of a "skip-lines" value:

    @region <region-tag> [skip-lines]

might be extended/replaced by:

    @region <region-tag> [region-label]
    ...
    @regionlabel abc
    ...
    @endregion [region-tag]

Where 'abc' is the optional 'region-label'.

Honestly, though, I think that a simple,

    @region <region-tag>
    ...
    @endregion <region-tag>

should be enough without either a 'skip-lines' or 'region-label'
modifier.  If I wanted some offset, why not simply have a different
region tag for it instead of some number of lines offset because this
number @b @e MUST change when lines are added or deleted in the skip
region, <b>MAKING THE WHOLE '@region... skip-lines]' CONSTRUCTION QUITE
FRAGILE<b>.

Instead, use of multiple region tags is
significantly more robust and may @e always be properly parsed by
Doxygen:

    @region region_tag_1
    ...
    @region region_tag_2
    ...
    @region region_tag_3

    ... common inclusion


    ... end the regions in any order,
        even with sequential lines:

    @endregion region_tag2

    ...

    @endregion region_tag_3
    @endregion regsion_tag1

Any missing tag of the pair @region/@endregion would be flagged as an
error, perhaps reading until end of file and flagging both a missing
@endregion and EOF conditon?  Would it als make more sense to scrub the
[skip-lines] and/or [region-label] concept entirely?

Anyway, I hope this helps.  Comments are solicited.



Dan Lydick