Suggested changes for newLISPDoc

[hsmyers]

I'd like to suggest some small changes for newLISPDoc. The are:

Remove the restrictions on <h1> - <h4>, i.e. these lines:

Code: Select all

h1, h2, h3, h4 {
	font-family: Georgia, Times New Roman, Times, serif;
   	font-size: 110%;
	}

Add <hr> to the approved list:

Code: Select all

	(replace "<hr>" text "[hr]")
	(replace "</hr>" text "[/hr]")

And:

Code: Select all

	(replace "[hr]" text "<hr>")
	(replace "[/hr]" text "</hr>")

Then add this function:

Code: Select all

(define (format-see-also text)
	(letn (link-list (string "<b>see also: <b> - "))
		(dolist (lnk (parse text)) 
			(push (string "<A HREF=\"#_" lnk "\">" lnk "</A>&nbsp;&nbsp;") link-list -1))
	(string link-list))
)

And a corresponding line of code:

Code: Select all

			(replace ";; *@see-also (.*?)\n" page (format-see-also $1) 0)

This would provide better control over headline size, horizontal rules for useful divisions and the ability to cross-reference using existing tags.

--hsm

[Lutz]

Thanks hsmyers, I removed the font-size restrictions and added <hr> to the list of protected HTML. I wonder if it would work to protect the <style> tag too, and then people can add their own style if they want to.

But the see-also stuff is not working, leaves all text bold behind it (please always test all changes) and I also think, a corresponding <a name ....> tag would have to be replace-protected, unless you intended the tag only be used for the documented functions?

You can simulate the see-also tag with the following:

Code: Select all

;; <b>see also:</b> @link #this this and @link #that that

I am trying to keep tags in newlispdoc to an absolute minimum to make adoption of newlispdoc as easy as possible.

Lutz

[hsmyers]

Interesting... The see-also tag works on my machine running W2k with FireFox. I didn't think to test for other combinations. The placement of the one line conversion is immediately after the similar conversion for @return. I found that otherwise all I got was @see-also as text including the value(s). I wonder what would cause what you see? And you are correct in that I had only the documented functions in mind; adding the name tag would allow jumping to blocks of text as well. Quite useful.

[Lutz]

The problems seems to be here:

Code: Select all

(string "<b>see also: <b> - "))

The bold tag doesn't close, also, the underscore between the # and the name of the functions in the links prevents finding them (on Safari):

Code: Select all

"<A HREF=\"#_" lnk "\">"

Name tags look like this: <a name="MySQL_query"></a>. So you would have to enter MySQL_query which would also be displayed like this and that doesn't look right.

Its better to stay with the workaround:

;; <b>see also:</b> @link #MySQL_query MySQL:query and @link #MySQL_connect MySQL:connect

as it is more flexible allowing customized text and multiple links.

Lutz

[hsmyers]

Ah! Trust me to trip on a typo. Yes that would certainly explain your result and bad eyesight would explain me not noticing my result!! The underscore is there because that is what is generated for each function:

Code: Select all

<p></p><center>- &sect; -</center><p></p>

<a name="_piece"></a><h3><font color=#CC0000>piece</font></h3>
<b>syntax: (<font color=#CC0000>piece</font> <em>square</em>)</b><br/>
<b>parameter: </b><em>square</em> - which square of the board<br/>
<p><b>return: </b>the piece found at <em>square</em> of the board</p>

<p></p><b>example:</b><blockquote><pre> (piece "e1")
 => "k"</pre></blockquote>
<p></p><center>- &sect; -</center><p></p>
<a name="_side"></a><h3><font color=#CC0000>side</font></h3>
<b>syntax: (<font color=#CC0000>side</font> <em>square</em>)</b><br/>

I was just trying to take advantage of what was already generated for the index I believe.

I see your point about multiple word tags. Hadn't thought about it that way since I was only doing function names.


--hsm

[Lutz]

... now, what can we do to encourage everybody to comment using newlispdoc ?-). The @index tag, introduced a while ago permits linking to other, external module collections, see here:

http://www.newlisp.org/modules/

and click on "Index: EnFeautec", which leads you to DMI's collection of modules. I also accept modules to host on newlisp.org, if they are maintained and have either a a link to a maintained original or an email address of the author for support.

Lutz

[hsmyers]

After all of these years I still have no idea of how to encourage documentation. Even when it is built into the language as in Perl and POD (plain old documentation) I've seen programmers unaware of what was at their fingertips. Thankfully CPAN generally has excellent documentation. One of the reasons that I switched to newLISP was precisely because of newLISPDoc. It is a mystery to me why it is not used by everyone. When I finish my Chess/PGN(Portable Game Notation) module I will certainly take advantage of you hosting service as I think sharing code makes better coders of us all.

--hsm

[cormullion]

One of the projects in my todo list is a script that inserts newLISPdoc outlines into newLISP source. I was planning to modify the tokenized source of a newLISP file and insert empty documentation strings before (or after?) the relevant function definitions. I have no idea whether it will work or not...

[hsmyers]

Good idea, all things being equal I have a preference for 'before a function'-- no reason really just seems right. I balance that by having the example after the function. Have you thought of adding the colorized code?

--hsm

[Cyril]

Add <hr> to the approved list:

Code: Select all

	(replace "<hr>" text "[hr]")
	(replace "</hr>" text "[/hr]")

Are you sure <hr> should be processed in this exact way? It is not open/closing tag and therefore cannot appear in </hr> form. On the other hand, it can have a slash after tag, as <br> does.

Oops! The forum doesn't allow me to insert tags with slash after them, so I am bound to type [hr/] and [br/] and say "replace square braces with angle ones".

[cormullion]

I haven't thought of much yet. It's just another entry in my "things that would be cool to do if it's not too difficult for me and if I can't get someone more suitable to write it instead" list. :)

[Cyril]

... now, what can we do to encourage everybody to comment using newlispdoc ?-).

My two kopecks are supporting documentation comments in my Vim highlighting mode. See here how your cgi.lsp module looks in Vim, including documentation in comments.

The @index tag, introduced a while ago permits linking to other, external module collections, see here:

At this point I have suddenly realized that my support of doc comments in Vim is a bit out of date. So I have released version 1.19 one hour ago. Changes: @index keyword is supported, <hr> tag is supported. The later is not yet in my newlispdoc, but I am anticipating the future! ;-) And, by the way, I support it in [ht/] form, not is [/ht] form -- the later is just wrong. Of course plain [hr] is working too. (Square brackets instead of angle ones because of forum limitations).

[hsmyers]

Cyril you are correct about \<hr>! I plead lack of sleep while coding ;) I've begun adding the necessary material to a .stx file for EditPlus that will do the skeleton framework for me, both the @syntax material and @example. As I use it over time I'll manage text replacement for the functions I use most. I'd move up to vi/vim except that emacs got to me first!

--hsm