XN-Docs: an online AutoHotkey script documentation builder

AutoHotkey Community
Let's help each other out

FAQ

Memberlist

Profile

XN-Docs: an online AutoHotkey script documentation builder
Goto page Previous 1, 2, 3, 4, 5, 6 Next

AutoHotkey Community Forum Index -> General Chat

View previous topic :: View next topic

Author

Message

Titan

Joined: 11 Aug 2004
Posts: 5376
Location: /b/

Posted: Mon Sep 24, 2007 4:33 pm Post subject:

Done, now it's officially RC1. Please test your scripts and let me know if you get any errors. _________________

majkinetor

Joined: 24 May 2006
Posts: 3644
Location: Belgrade

Posted: Tue Sep 25, 2007 8:58 am Post subject:

This is what I get for previously parsed scripts.

Quote:

Fatal error: Call to undefined function: report()

_________________

Titan

Joined: 11 Aug 2004
Posts: 5376
Location: /b/

Posted: Tue Sep 25, 2007 9:21 am Post subject:

Typo fixed. Thanks. _________________

majkinetor

Joined: 24 May 2006
Posts: 3644
Location: Belgrade

Posted: Tue Sep 25, 2007 9:31 am Post subject:

1. Title description isn't taken into account:

Code:

; Title: Ini
;Helper functions for easier ini file handling

2. Return is always empty.

3. Call example also has DynTemplate missparsed - its new section with its own code.
_________________

Titan

Joined: 11 Aug 2004
Posts: 5376
Location: /b/

Posted: Tue Sep 25, 2007 9:54 am Post subject:

majkinetor wrote:

1. Title description isn't taken into account:

It works for me.

majkinetor wrote:

2. Return is always empty.

Added 'return' to switch case, previously it was only 'returns'.

majkinetor wrote:

3. Call example also has DynTemplate missparsed - its new section with its own code.

That's how it is. Code sections should only be within the examples section. I'm unwilling to alleviate this limitation as it breaks consistency on the page.
_________________

majkinetor

Joined: 24 May 2006
Posts: 3644
Location: Belgrade

Posted: Tue Sep 25, 2007 10:12 am Post subject:

Quote:

I'm unwilling to alleviate this limitation as it breaks consistency on the page.

What kind of reason is that ?! Breaking consistency of the page ? Laughing

So, as you finally realised custom parser is the best solution, I will try to find time to formalize you syntax if you still want that.

Quote:

Added 'return' to switch case, previously it was only 'returns'.

It was returns in my case, however it was still empty.

I am sending you file on PM.
_________________

Titan

Joined: 11 Aug 2004
Posts: 5376
Location: /b/

Posted: Tue Sep 25, 2007 11:27 am Post subject:

majkinetor wrote:

What kind of reason is that ?! Breaking consistency of the page ? Laughing

In all honestly not only is it to do with aesthetics but it will be a real pain to change the XSLT to write code blocks in different areas.

majkinetor wrote:

So, as you finally realised custom parser is the best solution, I will try to find time to formalize you syntax if you still want that.

Sure, go ahead.

majkinetor wrote:

It was returns in my case, however it was still empty.

Sorry, it's fixed now.

majkinetor wrote:

I am sending you file on PM.

You forgot to put a colon after 'Examples' under the LoadKeys function. Apart from that XN-Docs produces, from what I can see the expected result.
_________________

majkinetor

Joined: 24 May 2006
Posts: 3644
Location: Belgrade

Posted: Tue Sep 25, 2007 11:47 am Post subject:

Quote:

In all honestly not only is it to do with aesthetics but it will be a real pain to change the XSLT to write code blocks in different areas.

Ye, esthetics shouldn't be your concern.

Quote:

You forgot to put a colon after 'Examples'

I was talking about Title and its description. There is still no description of the library.

Then Group keyword is probably not handled, but lets leave that after formalisation.
_________________

Titan

Joined: 11 Aug 2004
Posts: 5376
Location: /b/

Posted: Tue Sep 25, 2007 12:49 pm Post subject:

majkinetor wrote:

Ye, esthetics shouldn't be your concern.

Why not? It's paramount.

majkinetor wrote:

I was talking about Title and its description.

They both work now.

majkinetor wrote:

Then Group keyword is probably not handled

It already was, didn't you notice the copyright notice?
_________________

majkinetor

Joined: 24 May 2006
Posts: 3644
Location: Belgrade

Posted: Tue Sep 25, 2007 1:47 pm Post subject:

Quote:

It already was, didn't you notice the copyright notice?

Yes I did, but not everything I wrote was there. Anyway, group is just a synonime for Title in Ndoc, but it seems you devised new copyright tag out of it.

Quote:

Why not? It's paramount.

When you grow up you will understand.
_________________

Titan

Joined: 11 Aug 2004
Posts: 5376
Location: /b/

Posted: Tue Sep 25, 2007 2:46 pm Post subject:

majkinetor wrote:

Yes I did, but not everything I wrote was there.

It's just been fixed.

majkinetor wrote:

Anyway, group is just a synonime for Title in Ndoc, but it seems you devised new copyright tag out of it.

Group and About are seen as prefixes and ignored when they have another keyword in front of them. I don't know if this is a good implementation but all will become apparent to me after you post the syntax specification.

Edit: here's the PHP source code for the RDF conversion. Scrutinize if you will:

Code:

// [for styling this code block]
#CommentFlag //

function tordf($scr, $file = '', $is_scr = true, $col = false) {
$scr = "\n" . preg_replace('/(?:^|\n)(?!\/\*|\*\/)\W+(?=\n|$)/', '', str_replace("\n\n", "\n", str_replace("\r", "\n", $scr))) . "\n";
if ($is_scr) {
 preg_match('/^#CommentFlag\s*(.+)\s*/im', $scr, $cf);
 $cf = $cf[1] == '' ? ';' : $cf[1];
 if (preg_match_all("/(?<=\n)\s*\/\*.*\s*\*\/|(?<=\n$cf)[^\n]+\n/s", $scr, $var))
 $scr = join('', $var[0]);
 else exitc('No comment sections found in script.');
}
else $scr = preg_replace('/^;/m', '', $scr);
//$scr = preg_replace('/(?:^|\n)\s*(?!-|\w+\s*[\-:])(.*)\r?\n\s*(?!\w+\s*[\-:])(?!o\s)(\w.*)/', '$1 $2', $scr);
// zomg this bit is important:
preg_match_all('/(?:\n|^)\s*(?:(?:About|Group)\s*:[\t ]*(\w+(?:[\t ]+\w+)?)\s*:?|(\w+(?:[\t ]+\w+)?)\s*:)\s*(.*?)\s*(?=\n\s*\w+(?:[\t ]+\w+)?\s*:|$)/si', $scr, $sec);
//var_dump($scr); exitc();
$f = -1;
for ($i = 0; $i < count($sec[0]); $i++) {
 $val = htmlspecialchars($sec[3][$i]);
 switch (strtolower($sec[$sec[1][$i] ? 1 : 2][$i])) {
 case 'topic':
 case 'title':
 foreach (explode("\n", $val) as $line) {
 if (!$d['t'])
 $d['t'] = $line;
 else {
 if (preg_match('/v(?:er(?:sion)?)?\s*([\d\.]+)/i', $line, $var))
 $d['v'] = $var[1];
 if (preg_match('/by\s*(\w+)/i', $line, $var))
 $d['a'] = $var[1];
 if (!preg_match('/v\d|version|by/i', $line))
 $d['d'] = $line;
 }
 }
 break;
 case 'function':
 $fx[++$f]['t'] = explode("\n", $val, 2);
 break;
 case 'parameters':
 foreach (explode("\n", $val) as $line)
 if (preg_match('/^\s*(\w+)\s*-\s*(.+)/', $line, $val_sub))
 $fx[$f]['p'][] = $val_sub;
 break;
 case 'examples':
 case 'example':
 $ex_a = explode("\n", $val);
 $var = '';
 for ($ex_i = 0; $ex_i < count($ex_a); $ex_i++) {
 if ($ex_i == 0) {
 preg_match('/^(?:>|>|\||:)?(\s*)/', $ex_a[$ex_i], $ex_s);
 $ex_s = (string)strlen($ex_s[1]);
 }
 $var .= "\n" . preg_replace("/^(?:>|>|\||:)?\s{0,$ex_s}/", '', $ex_a[$ex_i]);
 }
 $fx[$f]['e'][] = ltrim(rtrim($var));
 break;
 case 'return':
 case 'returns':
 $fx[$f]['ret'] = $val;
 break;
 case 'remark':
 case 'remarks':
 $fx[$f]['r'][0] = $val;
 break;
 case 'about':
 case 'lisence':
 case 'license':
 if (preg_match('/v(?:er(?:sion)?)?\s*([\d\.]+)/i', $val, $var))
 $d['v'] = $var[1];
 if (preg_match('/by\s*(\w+(?:\s+(?:and|\&|\+|&)\s+\w+)*)/i', $val, $var))
 $d['a'] = $var[1];
 foreach (explode("\n", $val) as $line)
 if (!preg_match('/v\d|version|by/i', $line) and !empty($line))
 $d['l'] .= "; " . ltrim(ltrim(ltrim($line), '-'));
 break;
 default:
 $var = count($fx[$f]['r']);
 $fx[$f]['r'][$var > 0 ? $var : 1] = ' ' . $sec[$sec[1][$i] ? 1 : 2][$i] . ': ' . $val;
 }
}
//var_dump($d); exitc();
$rdf = '';
if ($d['t'])
 $rdf .= "<dc:title>{$d['t']}</dc:title>";
if ($d['d'])
 $rdf .= "<dc:description>{$d['d']}</dc:description>";
if ($d['a'])
 $rdf .= "<dc:creator>{$d['a']}</dc:creator>";
if ($d['v'])
 $rdf .= "<xnd:version>{$d['v']}</xnd:version>";
if ($d['l'])
 $rdf .= '<dc:rights>' . substr($d['l'], 2) . '</dc:rights>';
for ($i = 0; $i < count($fx); $i++) {
 $rdf .= '<xnd:method dc:title="' . $fx[$i]['t'][0] . '">';
 if ($fx[$i]['t'][1])
 $rdf .= '<dc:description>' . ltrim(rtrim($fx[$i]['t'][1])) . '</dc:description>';
 if ($fx[$i]['p']) {
 $rdf .= '<xnd:params><rdf:Seq>';
 foreach ($fx[$i]['p'] as $var)
 $rdf .= '<rdf:li><dc:description dc:title="' . $var[1] . '">' . $var[2] . '</dc:description></rdf:li>';
 $rdf .= '</rdf:Seq></xnd:params>';
 }
 if ($fx[$i]['ret'])
 $rdf .= "<xnd:returns>{$fx[$i]['ret']}</xnd:returns>";
 if ($fx[$i]['e']) {
 $rdf .= '<xnd:examples>';
 foreach ($fx[$i]['e'] as $var)
 $rdf .= '<xnd:script>' . ($col ? syntax($var, $col - 1) : $var) . '</xnd:script>';
 $rdf .= '</xnd:examples>';
 }
 if ($fx[$i]['r']) {
 $rdf .= '<xnd:remarks dc:type="text/html">';
 for ($var = 0; $var < count($fx[$i]['r']); $var++)
 $rdf .= str_replace("\n", ' ', $fx[$i]['r'][$var]);
 $rdf .= '</xnd:remarks>';
 }
 $rdf .= '</xnd:method>';
}
$rdf = '<?xml version="1.0" encoding="utf-8"?><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:xnd="http://ccgi.inspiration3.plus.com/ahk/xn-docs/ns-1" xmlns:html="http://www.w3.org/1999/xhtml" xml:lang="en-GB"><rdf:Description'
. ($file == '' ? '' : " rdf:about=\"$file\"") . '>' . $rdf . '</rdf:Description></rdf:RDF>';
//header('Content-type: text/xml'); exitc($rdf);
return $rdf;
}

majkinetor wrote:

When you grow up you will understand.

Well until then I've got to worry about placements of objects in a page for good structure and accessibility (dw, you're probably too old to understand).
_________________

majkinetor

Joined: 24 May 2006
Posts: 3644
Location: Belgrade

Posted: Tue Sep 25, 2007 3:10 pm Post subject:

Quote:

dw, you're probably too old to understand

Its not that. Its just nobody understands you.

Quote:

Here's the PHP source code for the RDF conversion

OMG, its full of REs Shocked

_________________

Titan

Joined: 11 Aug 2004
Posts: 5376
Location: /b/

Posted: Tue Sep 25, 2007 3:29 pm Post subject:

majkinetor wrote:

Its not that. Its just nobody understands you.

Sorry, I actually believed you learnt XSLT. The Examples section is reserved for code blocks whereas the Remarks section contains text, and handling two very different entities within the same container is difficult as it requires loops and specific parsing techniques to produce the correct spacing and styles.

majkinetor wrote:

OMG, its full of REs Shocked

I took that bulldozer to fifth gear Cool

This is why I wanted to stick with the official ndocs parser, but you managed to sway me. It will be better in the long run anyway.
_________________

majkinetor

Joined: 24 May 2006
Posts: 3644
Location: Belgrade

Posted: Tue Sep 25, 2007 6:08 pm Post subject:

Quote:

Sorry, I actually believed you learnt XSLT.

Nope, sorry Smile

I just know what it is used for. I know XML & XPATH very well.

Quote:

I took that bulldozer to fifth gear

In this times you call RE a buldozer ?
So what is everything else then ?
A space ship with space time singularity as drive engine ?

Quote:

It will be better in the long run anyway.

I gave you good reasons why Ndoc parser is not necessary. When I formalise syntax you will see that part of NDoc , dealing with single file, for "simple" language is preatty trivial.

Anyway, I really like idea to have web documentator for sinngle code file, what is usual with scripts. I imagine usability of your page will be quite big, out of AHK community (and hope). There are plenty of such languages there, very much used, for which u have 1 file library.

Then, after all, gluing several files together after 1 file works, if ppl demand that, can be done realy easy (producing single index.html that links all given files together...)
_________________

corrupt

Joined: 29 Dec 2004
Posts: 2421

Posted: Wed Sep 26, 2007 4:24 am Post subject:

Titan wrote:

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.

IE not supported... Shocked

. Is this still the case? If IE is now supported then I can post another bug report from my latest testing tonight if you'd like Smile

. Btw, would it be possible to produce a separate file for each function instead so that we could optionally create a .chm file from the generated documentation files? If that doesn't seem practical then I guess the alternative would be for us to manually break the functions into separate files first...

Display posts from previous:

	AutoHotkey Community Forum Index -> General Chat	All times are GMT Goto page Previous 1, 2, 3, 4, 5, 6 Next
Page 4 of 6

You can post new topics in this forum
You can reply to topics in this forum