MaxCoderz

for your 1 bit pleasure!

All times are UTC




Post new topic Reply to topic  [ 6 posts ] 
Author Message
PostPosted: Sun 13 Apr, 2008 9:45 am 
Offline
Maxcoderz Staff
User avatar

Joined: Thu 01 Dec, 2005 9:04 am
Posts: 227
Location: Melbourne, Australia
I've been working on my own take on a asm source documentation generator and thought I'd solicit some input.

This is based on Timendus' asmdoc utility which he created for Vera, but with my own personal twist to make it more flexible and less prone to parsing errors.

I have created a test page using a work-in-progress generator at my googlepages site.

I think it will be easiest to explain this by example, so here is one of the comment blocks used to generate the file:

Code:
;-------------------------------------------------------------------------------
;@doc:routine
;
; === alClip3DPolygon ===
;
;  Clips a 3D polygon against the view frustum. Input is supplied in 16-bit 3D
;  co-ordinates and output is 8-bit 2D projected co-ordinates.
;
; INPUTS:
;  REGISTERS
;  * A  - Number of vertexes in the polygon.
;  * BC - Address of vertex index list
;  * HL - Address of clipping data
;  * DE - Address of vertex list
;  * IX - Output address
;
; OUTPUTS:
;  REGISTERS
;  * A  - Number of vertexes in clipped polygon (0 if completely culled).
;  * F  - Zero flag set if polygon was culled.
;
; DESTROYED:
;  REGISTERS
;  * BC, DE, HL, IX
;
;  MEMORY
;  * g_alTempRAM - first 21 bytes destroyed
;
;@doc:end
;-------------------------------------------------------------------------------


The parser starts off by looking for pure comment lines. It is then kicked into action by an @doc: declaration. This helps prevent the parser from choking on code it wasn't meant to analyse.

The identifier following @doc: can be any name. In the test I used "routine" for code, "global" for global variables and "file" for file descriptions. The parser doesn't care (except for @doc:end, which is a reserved word) - it doesn't (yet) use this information, although it probably will later when I get around to index generation.

What it does do is include that name in the class specification in the HTML. ie:

Code:
<div class="routine identifier">


The "identifier" is a class name which is included for all the @doc:s. The purpose of this is it allows you to use CSS to specify a basic style for everything, and then override it with more specific styles for routines/data/files etc.

Getting back to the point, the parser doesn't actually generate any code at this point. The @doc: just tells it what class to use for any following definitions.

The actual identifiers are declared Vera-style, using ===. Once it finds an identifier, it generates a header for it.

The next step is the descriptors. The descriptors are what actually supplies the information about the routine. When the parser encounters an === identifier ===, it creates a default descriptor called, oddly enough, "description". It inserts any text following the identifier into the description until it encounters another identifier, @doc:end or a custom descriptor.

Custom descriptors are declared by a single word on a new line followed by a colon (such as "INPUTS:" in the example). Each descriptor, including the default "description", receives it's own div as follows:

Code:
<div class="name descriptor">


As with "identifier", "descriptor" is a generic class name for styling purposes. The "name" is name of the descriptor, converted to lowercase. So the "INPUTS:" name becomes:

Code:
<div class="inputs descriptor">


The only other thing is the format of the descriptors. Blocks of regular text will just be passed straight through after being wrapped in <p> </p> tags. Consecutive lines of text are concatenated into the same block. If there is an empty line separating two blocks of text, they receive their own <p> tag.

You can also define bulletted lists using asterisks:
Code:
* item one
* item two


The lists are actually generated as 2 column tables. If a list item starts with a single word followed by a hyphen, it will split down the hyphen and put the name in the left hand side and the value in the right hand side.

If the item starts with a hyphen, it assumes it is a continuation of a previous entry and put everything in the right hand side, such as this:

Code:
BC - first line
   - second line


Anything else is just spanned across both columns.

If the line immediately before the first list item was not blank, it will be inserted as a caption to the list. (See "REGISTERS" in the example).

And that's about it! I'd like to hear your comments - especially how you think this would gel with your commenting style. I'd like this to be as reusable as possible.

_________________
"I don't know why a refrigerator is now involved, but put that aside for now". - Jim e on unitedti.org

avatar courtesy of driesguldolf.


Last edited by qarnos on Fri 16 May, 2008 8:47 am, edited 1 time in total.

Top
 Profile  
Reply with quote  
 Post subject:
PostPosted: Thu 15 May, 2008 7:04 pm 
Offline
Calc King
User avatar

Joined: Sun 23 Jan, 2005 12:37 am
Posts: 1727
Location: Netherlands
Looks like fun. How do you make it "less prone to parsing errors"? Maybe I could use some of it in Vera's tool :)

Two things I don't like about it:
- It parses to HTML (I kinda liked the idea of parsing to generic XML that can be used with anything - including a webbrowser with a bit of XSLT)
- I like the lay-out that I kinda ripped from Ben better :P But that's just a matter of stylesheet of course ;)

_________________
http://clap.timendus.com/ - The Calculator Link Alternative Protocol
http://api.timendus.com/ - Make your life easier, leave the coding to the API
http://vera.timendus.com/ - The calc lover's OS


Top
 Profile  
Reply with quote  
 Post subject:
PostPosted: Fri 16 May, 2008 6:58 am 
Offline
Maxcoderz Staff
User avatar

Joined: Thu 01 Dec, 2005 9:04 am
Posts: 227
Location: Melbourne, Australia
Timendus wrote:
Looks like fun. How do you make it "less prone to parsing errors"? Maybe I could use some of it in Vera's tool :)


Well, the main feature is the "@doc" think, which delimits the documentation so the parser doesn't try to parse stuff it shouldn't. I also use a list marker "*" rather that have the parser try to guess what is supposed to be a list. It also uses indentation as cues if it gets really confused.

I've added a pretty nifty z80 code parser - it can automagically detect blocks of code, wherever they are, and produce highlighted output with code aligned into columns for labels/opcode/operands/comments.

I am adding support for vera-style documentation, so you will be free to use it when it's working :) Hopefully I can release something functional this weekend.

Quote:
Two things I don't like about it:
- It parses to HTML (I kinda liked the idea of parsing to generic XML that can be used with anything - including a webbrowser with a bit of XSLT)


I agree, but I don't know jack about XSLT so I went with HTML. I am adding an XML backend, so you will be able to produce raw XML if that tickles your fancy.

Quote:
- I like the lay-out that I kinda ripped from Ben better :P But that's just a matter of stylesheet of course ;)


Well, my layout is my personal twist on a rip-off of your ripped off version of Ben's layout ;)

It's more just a "default look" until things are working properly.

_________________
"I don't know why a refrigerator is now involved, but put that aside for now". - Jim e on unitedti.org

avatar courtesy of driesguldolf.


Top
 Profile  
Reply with quote  
 Post subject:
PostPosted: Fri 16 May, 2008 8:49 am 
Offline
Maxcoderz Staff
User avatar

Joined: Thu 01 Dec, 2005 9:04 am
Posts: 227
Location: Melbourne, Australia
I've uploaded a new snapshot of the 3D engine documentation using EGADS - Easy Generation of Assembly Documentation from Source.

There are a few "test" routines - console.* - thrown in to check that the generator handles period separated names correctly. Check out the documentation for "console" and "console.writeln" to see what I am talking about.

link.

_________________
"I don't know why a refrigerator is now involved, but put that aside for now". - Jim e on unitedti.org

avatar courtesy of driesguldolf.


Top
 Profile  
Reply with quote  
 Post subject:
PostPosted: Tue 20 May, 2008 3:40 pm 
Offline
Calc King
User avatar

Joined: Sun 23 Jan, 2005 12:37 am
Posts: 1727
Location: Netherlands
qarnos wrote:
I don't know jack about XSLT so I went with HTML. I am adding an XML backend, so you will be able to produce raw XML if that tickles your fancy.

Quote:
- I like the lay-out that I kinda ripped from Ben better :P But that's just a matter of stylesheet of course ;)


Well, my layout is my personal twist on a rip-off of your ripped off version of Ben's layout ;)


Feel free to use my XSLT sheets and layout -- erm, Ben's layout ;) Once you've generated XML in the Vera fashion (sorry, don't have a DTD for you) it should more or less automagically work with it. I didn't know a thing about XSLT either when I started on it, but I used the Vera documentation as an excuse to learn about it :)

It sounds like your parser is a lot more complex than mine, which is a good thing because I don't plan to work on mine much, though it really needs a few bugfixes and improvements... So if your parser works for our code, and it's more advanced, I've got an excuse to switch and drop development of my own parser ;)

Either way, I don't have a lot of time to spare for Vera anyway...

_________________
http://clap.timendus.com/ - The Calculator Link Alternative Protocol
http://api.timendus.com/ - Make your life easier, leave the coding to the API
http://vera.timendus.com/ - The calc lover's OS


Top
 Profile  
Reply with quote  
 Post subject:
PostPosted: Tue 20 May, 2008 4:05 pm 
Offline
Maxcoderz Staff
User avatar

Joined: Thu 16 Dec, 2004 10:06 pm
Posts: 3064
Location: Croydon, England
I ripped the layout off from the VS2005 MSDN library. :roll:

Looking good, though. :)


Top
 Profile  
Reply with quote  
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 6 posts ] 

All times are UTC


Who is online

Users browsing this forum: No registered users and 5 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
cron
Powered by phpBB ® Forum Software © phpBB Group | DVGFX2 by: Matt