AW: Reusable module repository

doxygen: afaik there are two ways to "enable" rpg for doxygen. make a pre-run 
program which creates c-like syntax or write a pre-run program which creates a 
document which can be parsed by the doxygen backend (but feel free to read the 
doxygen faqs =). but in c there are no file decleration, etc... so the rpg 
specific things can not go into the docoumentation. that wouldn't be that good. 
(f. e. i would like to have all used files in the docu).

tags: IMO it is necessary to have configurable tags. someone would like to use 
\author in germany someone would like to use \Autor or @autor. it is definitly 
a necessity.

xml for storing the data is not that bad. but i think in the docu generation 
process it can lead to some complications.

perhaps we should talk about what to parse:
in my place there are over a thousand source members in one source file. it 
would take a lot of time to parse all the source members. so there should be a 
possibility to only parse one member so one could execute it as a post command 
for compilation (or the whole source file for updating the documentation in the 
night with a scheduled job). so we would have hundreds of xml files. its not 
easy to generate a docu with main pages and overview pages from several xml 
files (not impossible but more complex). if we have it all in one xml file than 
it will be hard to implement a parsing of a single source member (and at the 
info to the one xml file).

it would be nice to seperate the documentation by libraries in which the source 
files are. for example one tab in the html files for each library.

and last but not least ... in what language should the iledocs progamm be 
written ? rpg, java, rpg and java, c?
as long as it is rpg or java i think i can contribute something to the cause.

-----Ursprüngliche Nachricht-----
Von: rpg400-l-bounces@xxxxxxxxxxxx [mailto:rpg400-l-bounces@xxxxxxxxxxxx] Im 
Auftrag von AGlauser@xxxxxxxxxxxx
Gesendet: Freitag, 7. Juli 2006 18:32
An: RPG programming on the AS400 / iSeries
Betreff: RE: Reusable module repository

Some very good thoughts Aaron.

Aaron Bartell wrote on 07/07/2006 09:23:49 AM:

Here's how I would do RPGDocs if I started today. 
 (... an extensive plan - see below)

Sounds pretty reasonable.  I think maybe configurable tags could get kind 
of hairy ... unless the configuration is of the 'map your tags to our 
pre-defined tags' variety.  Other tools of this type seem to force 
pre-defined tags - but this would be a nice feature if it can be designed 
in at the beginning.

The best part about this is that a source crawl tool has most likely 

already

been written to do something like this, we would just have to mod it to 

go

over RPG. 

Mihael mentioned Doxygen, which seems pretty nice.  It even seems to have 
a way to add in other languages without to much trouble - of course I say 
that with just a quick peek at the website.  I have no experience with 
porting C++, but I would be interested in learning.

Anyways, those are my thoughts on the matter.  My forecast for free time 

to

do something like this in the near future is rainy at best. 

Me too, which is why I hope there will be enough interest to make starting 
an open-source project worthwhile.  If there are enough contributors I 
hope there will be enough momentum to keep things moving.


Adam



--- Extensive plan starts here! ----

1. Determine what meta-data I was going to collect and how I was going 

to

get it.
   1a. Files used
   1b. H spec options use
   1c. Variable name declarations (good for search if you want to find
all programs where INV# is used)
      1d. Procedure names
      1e. Sub routine names
   1f. Etc...
2. Determine what data you want to collect that is more on the comments
side.  For instance many programmers put comment blocks above each sub 

proc

and sub routine and also at the top of each program (see below).  Each 

shop

has different naming conventions for denoting or describing the info in 

the

comment block (e.g. @Program, Program Name:, Program Name...:, etc) so 

these

values would have to be configurable, again, I would use XML to 

configure

it.  The hard part with this is knowing when the data stops (i.e. what
happens when "@Description -" spans multiple lines?)

//**************************************************************************

*****************
      // @Program - BFXML (Build From XML)
      // @Author - Aaron Bartell
      // @Creation Date - 2006-07-07
      // @Description - Dynamically build an RPG program that will parse 

the

specified xml file.
      // @Notes - ALB 2006-07-07 This should go out in the next release
(v1.2).

//**************************************************************************

***************** 

3. Determine how to catalog the information after it has been "search" 

or

"crawled".  For this I would use an xml file like the following.  The 

beauty

of putting all this information in an xml document is that xml is easily
extended and can be consumed by MANY other tools out there (thinking of
Lucene http://lucene.apache.org/java/docs/). 

<library name="PROD1">
  <program name="BFXML" memberName="BFXML">
  <copybooks>
    <copybook name="ErrorCp" qualifiedName="QSOURCE,ErrorCP" />
    <copybook name="UtilCp" qualifiedName="QSOURCE,UtilCP" />
  </copybooks>
  <HspecOptions>
    <Hspec keyword="dftactgrp" value="*no"/>
  </HspecOptions>
  <tables>
    <table name="CONFIGPF" [put attributes for all F spec column data] 

/>

  </tables>
  <variables>
    <variable name="gError" type="datastructure" based="RXS_Error"/>
    ...
  </variables>
  <subprocedures>
    <subprocedure name="parseXML" exported="false">
      <parm name="pXmlFile" type="varying" length="256"/>
    </subprocedure>
  </subprocedures>
[there would be much more information, but you get the idea. Basically 

log

anything and everything about the program]
  </program>
</library>

4. Build an XSLT (XML Stylesheet Language Translation) from the 

generated

xml to a grouping of HTML files that could easily be published to a 

static

site similar to JavaDocs.  Of course we would want to make it not so 

static

because JavaDocs suck for searching (check out this next generation 

JavaDoc

called JavaRef: http://mowyourlawn.com/blog/?p=22). No reason we 

couldn't

create an application just like it for RPGDocs.

The above is just talking about searching the source and hasn't even 

gotten

into processing the API's that will give you interrelations like what 

other

modules are making use of module xyz.

#####################################################################################
Attention:
The above message and/or attachment(s) is private and confidential and is 
intended 
only for the people for which it is addressed. If you are not named in the 
address 
fields, ignore the contents and delete all the material. Thank you. Have a nice 
day.

For more information on email virus scanning, security and content
management, please contact administrator@xxxxxxxxxxxx
#####################################################################################