Suggested changes for newLISPDoc

Started by hsmyers, February 28, 2008, 01:41:50 AM

Previous topic - Next topic

hsmyers

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



Remove the restrictions on <h1> - <h4>, i.e. these lines:
h1, h2, h3, h4 {
font-family: Georgia, Times New Roman, Times, serif;
    font-size: 110%;
}

Add
to the approved list:
(replace "<hr>" text "[hr]")
(replace "</hr>" text "[/hr]")

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

Then add this function:
(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:
(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
\"Censeo Toto nos in Kansa esse decisse.\"—D. Gale \"[size=117]ℑ♥λ[/size]\"—Toto

Lutz

#1
Thanks hsmyers, I removed the font-size restrictions and added
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:


;; <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

#2
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.
\"Censeo Toto nos in Kansa esse decisse.\"—D. Gale \"[size=117]ℑ♥λ[/size]\"—Toto

Lutz

#3
The problems seems to be here:


(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):


"<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:



;; see also: @link #MySQL_query MySQL:query and @link #MySQL_connect MySQL:connect



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



Lutz

hsmyers

#4
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:


<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
\"Censeo Toto nos in Kansa esse decisse.\"—D. Gale \"[size=117]ℑ♥λ[/size]\"—Toto

Lutz

#5
... 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/">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

#6
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
\"Censeo Toto nos in Kansa esse decisse.\"—D. Gale \"[size=117]ℑ♥λ[/size]\"—Toto

cormullion

#7
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

#8
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
\"Censeo Toto nos in Kansa esse decisse.\"—D. Gale \"[size=117]ℑ♥λ[/size]\"—Toto

Cyril

#9
Quote from: "hsmyers"
Add
to the approved list:
(replace "<hr>" text "[hr]")
(replace "</hr>" text "[/hr]")



Are you sure
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
 does.



Oops! The forum doesn't allow me to insert tags with slash after them, so I am bound to type
and
 and say "replace square braces with angle ones".
With newLISP you can grow your lists from the right side!

cormullion

#10
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

#11
Quote from: "Lutz"... 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 http://wagner.pp.ru/~slobin/newlisp/cgi.lsp.html">here how your cgi.lsp module looks in Vim, including documentation in comments.


Quote from: "Lutz"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,
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
is working too. (Square brackets instead of angle ones because of forum limitations).
With newLISP you can grow your lists from the right side!

hsmyers

#12
Cyril you are correct about
! 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
\"Censeo Toto nos in Kansa esse decisse.\"—D. Gale \"[size=117]ℑ♥λ[/size]\"—Toto