OpenEuphoria

Re: Request: Enhancement to makedoc.ex

• Posted by Dan Moyer <danielmoyer at prodigy.net> Jan 11, 2007
• 613 views

c.k.lester wrote:
> 
> Is the makedoc program available in the archives the latest and greatest
> version? I did a search of the forum and it seems like others have added
> functionality to the original program. If you have an updated version of
> makedoc, please let me know.
> 
> One thing I'd like added to makedoc: the ability to capture the raw text
> of the file. For instance:
> 
> --/topic Includes
> --/desc The include files used for this program:
> --/raw_begin
> include this.e
> include that.e
> --/raw_end
> 
> Would output (in proper formatting):
> 
> Includes
> The include files used for this program:
> include this.e
> include that.e
> 
> Note that it outputs all text in the raw area, even if not a comment.
> This way, I don't have to duplicate lines of text in a comment, like:
> 
> --/topic Includes
> --/desc The include files used for this program:
> --include this.e
> --include that.e
> include this.e
> include that.e
> 
> Thank you! :)

c.k.,

I started to look into this, to see if I MIGHT be able to do it, and find
that it might not be possible, for this reason:

makedoc STOPS capturing text to include in documentation AS SOON AS IT 
ENCOUNTERS A *NON COMMENTED* LINE; this would include "include this.e".

to quote from the makedoc documentation:
---------------------------------
<quote>
3. EMBEDDING
---------------
The actual documentation is embedded in your source code files in the form of
Euphoria comments. This way, you can intersperse documentation with executable
code, thus hopefully making it easier to keep both code and documentation 
aligned with each other.

Of course, not all comments form a part of the published target document. Some
are purely there for the code reader's benefit. MakeDoc disinguishes between
normal comments and documentation elements by using a simple rule...

  A documentation element, or group of them, always begins with a line
  that starts with "--/topic" or "--/makedoc", and ends with the next
  non-comment line.
<end quote>
------------------------------------

Having said that, there are (at least?) two places that you would have to
look at in makedoc to attempt to accomplish what you want (I think):

fExtractData (which is the function which actually READS each line
              in a program, and decides whether to "retain" the line or not,
              for further processing), and,

fProcessData (which is the function that DOES whatever is intended by 
              the relevant makedoc keywords it encounters) 

And since fExtractData is where it decides to IGNORE any NON-COMMENTED lines,
that's probably where you would have add an exception, so those desired lines
would be saved;
then you'd have to make sure to HANDLE that exception in fProcessData.

If I have time (not really likely), I'll continue to look at it, but you might
have to wait until Derek comes back, or Matt or someone else who actually
understands what it's doing (& what they're doing!) might fix it for you. :)

Dan Moyer