1. Request: Enhancement to makedoc.ex
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! :)
2. Re: Request: Enhancement to makedoc.ex
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
3. Re: Request: Enhancement to makedoc.ex
Dan Moyer wrote:
> c.k.lester wrote:
> > One thing I'd like added to makedoc: the ability to capture the raw text
> > of the file.
> 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...
Dan, thanks for those clues. That might be enough for me to put something
klunky together that at least works for now. I've got an idea of how it
could work... I'll investigate today and let you know.
-=ck
"Programming in a state of Euphoria."
http://www.cklester.com/euphoria/
4. Re: Request: Enhancement to makedoc.ex
cklester wrote:
>
> Dan Moyer wrote:
> > c.k.lester wrote:
> > > One thing I'd like added to makedoc: the ability to capture the raw text
> > > of the file.
> > 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...
>
> Dan, thanks for those clues. That might be enough for me to put something
> klunky together that at least works for now. I've got an idea of how it
> could work... I'll investigate today and let you know.
One alternative is to make a preprocessor for makedoc. I've done this
to allow me to spread the docs around all the files of a project. Then
I have a batch file that runs the preprocessor to put all the doc-comments
into a single file. All you'd need to do would be to do this, plus
add your 'raw' comments and put them into the proper makedoc format.
That's probably easier than hacking at makedoc, but YMMV.
Matt
5. Re: Request: Enhancement to makedoc.ex
- Posted by c.k.lester <euphoric at cklester.com>
Jan 11, 2007
-
Last edited Jan 12, 2007
Matt Lewis wrote:
> cklester wrote:
> > Dan Moyer wrote:
> > > c.k.lester wrote:
> > > > One thing I'd like added to makedoc: the ability to capture the raw text
> > > > of the file.
> That's probably easier than hacking at makedoc, but YMMV.
Well, I had a go and it looks to be successful. I can now do something like
--/topic Required Standard Includes
--List of required standard include files
--/raw_start
include myfile.e
include thefile.e
--/raw_end
--/topic Required Custom Includes
--List of required custom include files
--/raw_start
include system/rawsql.e
include system/eudb.e
include system/ajax.e
--/raw_end
And it outputs what you'd expect... If anybody wants a copy, just lemme know.
Now you can include code snippets, etc., without having to comment it all and
without having to duplicate sections. It's handy for me; might not appeal to
everyone. :)
Thanks for the help, guys!
6. Re: Request: Enhancement to makedoc.ex
c.k.lester wrote:
>
> Matt Lewis wrote:
> > cklester wrote:
> > > Dan Moyer wrote:
> > > > c.k.lester wrote:
> > > > > One thing I'd like added to makedoc: the ability to capture the raw
> > > > > text
> > > > > of the file.
> > That's probably easier than hacking at makedoc, but YMMV.
>
> Well, I had a go and it looks to be successful. I can now do something like
>
> --/topic Required Standard Includes
> --List of required standard include files
> --/raw_start
> include myfile.e
> include thefile.e
> --/raw_end
>
> --/topic Required Custom Includes
> --List of required custom include files
> --/raw_start
> include system/rawsql.e
> include system/eudb.e
> include system/ajax.e
> --/raw_end
>
> And it outputs what you'd expect... If anybody wants a copy, just lemme know.
> Now you can include code snippets, etc., without having to comment it all and
> without having to duplicate sections. It's handy for me; might not appeal to
> everyone. :)
>
> Thanks for the help, guys!
Very good c.k.!! Yeah, I'd like a copy, at least to see how you did it,
& remember to notice when Derek gets back from vacation & let him know what
you've done, I suspect he'd be interested.
BTW, I thought "show" & "show_end" might have been better tags,
but hey, you did the code, so you got naming rights :)
Dan
