1. Request: Enhancement to makedoc.ex
- Posted by c.k.lester <euphoric at cklester.com> Jan 10, 2007
- 629 views
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
- Posted by Dan Moyer <danielmoyer at prodigy.net> Jan 11, 2007
- 612 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
3. Re: Request: Enhancement to makedoc.ex
- Posted by cklester <cklester at yahoo.com> Jan 11, 2007
- 607 views
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
- Posted by Matt Lewis <matthewwalkerlewis at gmail.com> Jan 11, 2007
- 614 views
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
- 616 views
- 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
- Posted by Dan Moyer <danielmoyer at prodigy.net> Jan 12, 2007
- 608 views
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