 |
AutoHotkey Community
Let's help each other out
|
| View previous topic :: View next topic |
| Author |
Message |
majkinetor
Joined: 24 May 2006
Posts: 3652
Location: Belgrade
|
 Posted: Thu Sep 13, 2007 10:33 am Post subject: |
 |
|
LOL, u just can't live with docu in code can't you ....
Well, its better U to addopt, then everybody to addopt to you.
_________________
 |
|
| Back to top |
|
 |
Titan
Joined: 11 Aug 2004
Posts: 5390
Location: /b/
|
| Posted: Thu Sep 13, 2007 1:05 pm Post subject: |
|
|
| corrupt wrote: | | A few things I noticed wih the current version: ... |
Thanks for the detailed bug report, they should be fixed soon.
| corrupt wrote: | | Would it be possible to add an option to upload a separate documentation file for processing instead of processing the file containing the script? |
Great idea, although it would be quite complex given the Natural Docs rigid API and PHP's tricky file upload handlers. I definitely plan to implement at one point.
| corrupt wrote: | | When I had accidentally selected a copy of a script that did not contain the generated documentation the following was displayed: ... |
I removed the interpreter command to suppress warning messages during testing and forgot to put it back in, which I now have just done. Error handling and exceptions will be improved at a later date.
| corrupt wrote: | | Would it be possible to give the user an option to either return to the form and select a different file or open the Converter window to enter the help data if the help data was not found in the script that was specified? |
I'll change the Converter to parse current information so it becomes more of an editor rather than just a generator. However integrating this with XN-Docs may not be feasible as it adds a huge overhead and requires an additional 'confirmation' step which some may find annoying.
_________________
 |
|
| Back to top |
|
|
Titan
Joined: 11 Aug 2004
Posts: 5390
Location: /b/
|
| Posted: Fri Sep 14, 2007 9:12 pm Post subject: |
|
|
Tonight's update includes many improvements, template examples and basic syntax highlighting. At the moment this is very privative, a few regexes are used to guess what words are commands and anything within quotes is coloured as expression type strings. I will only improve it if there's a demand or someone offers to help write a script parser in PHP.
Edit: now in beta!
_________________
|
|
| Back to top |
|
|
corrupt
Joined: 29 Dec 2004
Posts: 2436
|
| Posted: Sun Sep 16, 2007 7:23 pm Post subject: |
|
|
Nice improvements  . The converter seemed to be working well last night (although I only tested a couple of simple examples). The converter doesn't seem to be working today though. I was getting errors reported earlier and currently the fields for the functions aren't being displayed. Maybe someone is working on it, live... ? |
|
| Back to top |
|
|
Titan
Joined: 11 Aug 2004
Posts: 5390
Location: /b/
|
| Posted: Sun Sep 16, 2007 8:09 pm Post subject: |
|
|
Sorry, works now complete.
_________________
|
|
| Back to top |
|
|
corrupt
Joined: 29 Dec 2004
Posts: 2436
|
| Posted: Mon Sep 17, 2007 6:25 am Post subject: |
|
|
Apologies not necessary...  . I wasn't sure at first if there was a bug to report...
This version seems to work well . A couple things I've noticed:- If a file is submitted that contains functions without params., the fields for the Description, Returns, and Remarks do not seem to appear. The [show/hide] option appears on the right but doesn't seem to show any additional fields.
- Carriage returns entered in the Remarks field do not seem to be retained in the generated documentation
Is it currently possible to add example code without having to modify the generated html? |
|
| Back to top |
|
|
Titan
Joined: 11 Aug 2004
Posts: 5390
Location: /b/
|
| Posted: Mon Sep 17, 2007 7:09 pm Post subject: |
|
|
| corrupt wrote: | | If a file is submitted that contains functions without params., the fields for the Description, Returns, and Remarks do not seem to appear. The [show/hide] option appears on the right but doesn't seem to show any additional fields. |
If you're using IE it's currently unsupported.
| corrupt wrote: | | Carriage returns entered in the Remarks field do not seem to be retained in the generated documentation |
New lines are normalized to \r\n.
| corrupt wrote: | | Is it currently possible to add example code without having to modify the generated html? |
I added an example section.
_________________
|
|
| Back to top |
|
|
majkinetor
Joined: 24 May 2006
Posts: 3652
Location: Belgrade
|
| Posted: Tue Sep 18, 2007 11:55 am Post subject: |
|
|
Why is "Returns" contained in "Parameters".
Furthermore, this has buggy sidefect that if you document Return value with function accepting no parameters, Return section will not be shown.
I also notice problems with strings betwen ".
For instance "" will not be shown , "string" will be shown as string and
field=index will be shown as field="index".
It would be also cool to make "Title:" keyword working as list of functions doesn't seem appropriate in that manner.
_________________
|
|
| Back to top |
|
|
Titan
Joined: 11 Aug 2004
Posts: 5390
Location: /b/
|
| Posted: Tue Sep 18, 2007 2:54 pm Post subject: |
|
|
| majkinetor wrote: | | Why is "Returns" contained in "Parameters". |
Firstly because Chris groups returns with parameters (i.e. VarSetCapacity) and also it appears more consistent - e.g. in var := fx(p1), var should be explained first.
| majkinetor wrote: | | Furthermore, this has buggy sidefect that if you document Return value with function accepting no parameters, Return section will not be shown. |
Thanks, that can easily be fixed.
| majkinetor wrote: | | I also notice problems with strings betwen ". |
That's because I currently use a few pretty lousy regex to tidy HTML so it can be parsed with XSLT. Until I can find a good port for tidy on Debian I guess I'll have to refine my regex.
| majkinetor wrote: | | It would be also cool to make "Title:" keyword working as list of functions doesn't seem appropriate in that manner. |
What do you mean? If Title: is specified it overrides the default heading and page title.
_________________
|
|
| Back to top |
|
|
majkinetor
Joined: 24 May 2006
Posts: 3652
Location: Belgrade
|
| Posted: Tue Sep 18, 2007 3:02 pm Post subject: |
|
|
| Quote: | | What do you mean? If Title: is specified it overrides the default heading and page title. |
Ah sorry, my mistake, i used "topic" instead "title"
_________________
|
|
| Back to top |
|
|
majkinetor
Joined: 24 May 2006
Posts: 3652
Location: Belgrade
|
| Posted: Wed Sep 19, 2007 11:34 am Post subject: |
|
|
OK, the next step.
| Code: | ;-------------------------------------------------------------------------
; Function: HexView
;
; Overview:
; o Hexa, asci & struct display of input data
; o Synchronized scrolling
; o Customizable GUI appeareance
; o More then 1000 Win API structures included and you can define your own
; o Reverse interpretation of structures using - in front of structure name
; o Status bar containing offset and number of bytes of selection
; o Grab string out of struct field address using double right click on struct member
; o Copy struct field using left double click on struct member
;
; Parameters:
; pAdr - Address of the input data
; pByteNo - Number of bytes to show
; pActiveTab - Optional tab name to activate upon startup. This overrides saved registry
; setting.
;
; Remarks:
; o HexView comes with *Structures.str* file which contains list of Win SDK structure definitions
; to be used in struct view. This file is first searched in the scripts folder then in Lib folder.
; You can also set struct definitions manually by filling *HexView_structList* variable.
; Each struct definition must end with `r`n. See Structures.str for the format of structure definition.
;
; Examples:
;> s := "0123456789ABCDEF"
;> HexView(&s, 32)
;>
;> VarSetCapacity(s, 32)
;> NumPut(11, s, 0), NumPut(12, s, 4)
;> NumPut(13, s, 8), NumPut(14, s, 12)
;>
;> HexView_structList = [SIZE:|x D|y D`n[RECT:|a1 D|a2 D|a3 D|a4 D ;don't load Structures.str file
;> HexView(&s, 132, "struct")
;>
;
; Dependencies:
; <Mem>, <CmnDlg>, <Anchor>
;
; About:
; - v3.0 by majkinetor. See http://www.autohotkey.com/forum/topic17858.html
; - Licenced under GNU GPL <http://creativecommons.org/licenses/GPL/2.0/>.
; |
Also, I noticed Examples on Call are not quite good, probably because custom keyword is used again. Dyn template is given as code section under its own section, and examples are bellow in section "Examples". So, DynTemplate is not example, its just another code section.
Q:
Is it perhaps easier to create custom parser, based on Natural Docs ? If you want I can formalize syntax for you (and perhaps add some things Natural Docs is missing). It will require some work though >> 3 mins.
_________________
|
|
| Back to top |
|
|
Titan
Joined: 11 Aug 2004
Posts: 5390
Location: /b/
|
| Posted: Wed Sep 19, 2007 5:37 pm Post subject: |
|
|
Properly supporting dynamic custom keywords is impossible given the strict structural requirement of XSLT. Therefore use of advanced Natural Docs features will be unsupported for the time being.
| majkinetor wrote: | | Is it perhaps easier to create custom parser, based on Natural Docs ? |
It won't change the fact I just mentioned above. Plus converting 900kb of Perl code to PHP would take forever. Instead it might be an idea to write a Perl script using Natural Docs API to directly output metadata in a form XSLT will be able to parse. However I have little experience with Perl so it's not something I can do right now.
_________________
|
|
| Back to top |
|
|
Titan
Joined: 11 Aug 2004
Posts: 5390
Location: /b/
|
| Posted: Thu Sep 20, 2007 3:36 pm Post subject: |
|
|
I just had an idea: all custom sections could be put under Remarks as subsections. An advantage with this is that no new RDF tags need to be created and HTML code can be directly embedded (i.e. tables, lists and bold text), although the placement of sections will be rearranged. If you could formalize the syntax I will adapt the parser to modify the documentation accordingly.
_________________
|
|
| Back to top |
|
|
majkinetor
Joined: 24 May 2006
Posts: 3652
Location: Belgrade
|
| Posted: Fri Sep 21, 2007 9:51 am Post subject: |
|
|
I am not familiar with RDF. I was reading few topics about it after you implemented this but still have no practical xperience.
| Quote: | | Properly supporting dynamic custom keywords is impossible given the strict structural requirement of XSLT. |
Why ?
I mean, all those sections behave the same, they are the same, have only different title. So, perhaps another design, where you parse sections, and title is only 1 of the attributes of section.
So, we would have something like this:
1. Title
2. Function
3. Parameters
4. Section
5. Code
Each section can contain code section which is in natural docs written as ;>.
HTML would be really really nice addon to official natural docs rules.
The section is simply anything that has empty line before it, and starts the line with "Title:". Acctually ":" is something that marks new section. Empty line per se just creates paragraph. So, if you write "Title :" that will not create section as ":" is separated from title.
Fundamentaly, there is also no difference between Parameters and Section. "Parameters" is the same as any other section having enumeration in it.
So, I think this can be handled by XSLT pretty easily.
| Quote: | Plus converting 900kb of Perl code to PHP would take forever. Instead it might be an idea to write a Perl script using Natural Docs API to directly output metadata in a form XSLT will be able to parse
|
I wasnt talking about converting Perl code, but writting new parser for this. After all, Natural docs is not about single code file proccessing. The fact that u have only 1 file to process significantly reduces complexity of the project. NDoc creates all kind of things - glosaries, can decipher namespaces per se, can understand classes, scopes, make glossary, index, embed imagaes, AJAX search etc...
But, now, U don't have to think about those things. U can only create parser that will be compatibile with NDoc, just to have possibility later to create documentation with NDoc to have all those mentioned additional goodies (or not, that is the question that first have to be solved)
Perl should be pretty good language for such text manipulation as successor of langugaes for pure text manipulation, so I doubt that will be complex project, maybe a week with all testing and additional expanding.
If you think those ideas are good, I will make you the gramar to be parsed.
_________________
|
|
| Back to top |
|
|
Titan
Joined: 11 Aug 2004
Posts: 5390
Location: /b/
|
| Posted: Fri Sep 21, 2007 3:11 pm Post subject: |
|
|
| majkinetor wrote: | | Quote: | | Properly supporting dynamic custom keywords is impossible given the strict structural requirement of XSLT. |
Why ? |
For reasons I can't be bothered to explain. If you really did your homework you would know why  The closest you can get is a dedicated container with any number of children that can be iterated over in a predetermined way. I chose the Remarks section as the candidate for this. You can examine the code for XN1 to get a better understanding.
| majkinetor wrote: | | Perl should be pretty good language for such text manipulation as successor of langugaes for pure text manipulation, so I doubt that will be complex project, maybe a week with all testing and additional expanding. |
If you wish to contribute some code go ahead. I'll stick with the Natural Docs parser for the moment and possibly write my own AutoHotkey-specific version in PHP later on. Something like this wouldn't affect the end result for the user anyway; my main aim is to get XN-Docs fully working asap. so people can start distributing stdlib compatible scripts.
-----
Edit: total change of heart, I decided that an integrated parser is best. It was easier than I expected and it's almost ready to go live - I just need to iron out a few quirks in the regex which cause odd results with rogue syntax like that of majkinetor's.
Also, as with all my works source code is fully open. For security reasons it will only be available for download once version 1 is officially released, however anybody is welcome to parts of the code on request.
_________________
|
|
| Back to top |
|
|
|
|
You can post new topics in this forum
You can reply to topics in this forum
|
Powered by phpBB © 2001, 2005 phpBB Group
|
FAQ
Search
Memberlist
Register
Profile
Log in to check your private messages
Log in
