Subject: [clisp-list] working on Implementations Notes layout

From: "Hoehle, Joerg-Cyril" <[email-masked]>
Date: Thu May 22 00:40:06 2003

Hi,

LIN8080 wrote:
>In Impnotes.html - 1 564 205 - version 2.30.1 
>with: last modified 2003-05-15
>I do some layout changes. The important are:

Uh oh. This seems quite unfortunate to me since impnotes.HTML is not the place to work on. The HTML is automatically generated from a impnotes.XML (Docbook XML).

So instead of improving mechanically generated HTML, I believe the only viable way is to change the transformation of XML (Docbook) into HTML.
Sam already plays with such transformations, since CLISP typically comes with one huge impnotes file, while clisp.cons.org also has a split version (every chapter in a separate file), which is more user-friendly for external reference (URLs). Comparing various impnotes.html files (clisp-2.27, 2.28 etc.), you'll see quite some layout changes Sam did.

See the CVS online repository
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/clisp/clisp/doc/

I fear that you wasted some time working on .html. You'll probably have to learn about DSL, e.g. see doc/impnotes.dsl, which influences how impnotes.XML gets translated into impnotes.HTML, or you propose another way of turning docbook XML into html. I never looked into dsl myself. I still have to learn docbook (and still am no friend, to say the least, of the verbosity of XML and thus docbook).

Furthermore, impnotes.html from clisp 2.30 or 2.30.1 is almost outdated as soon as it appears. The up-to-date source is always in CVS. But Sam certainly accepts patches to released versions of CLISP (even though he always begs for patches against CVS, at least for source code).

>- file-size is now 849 822 bytes
I'm pretty sure there's room for improvement. E.g. impnotes for 2.27 was roughly this size, while 2.28 was >1MB. Some content was added, but also some of the HTML generated differently.

My personal opinion is also that there's a bit too much of cross-linking to CLHS. Every time e.g. CHARACTER appears in text, I see no need to have that link to CLHS. When I browse impnotes, I always have to check the status line to see "is this a link to another interesting section or is this yet another boring link to CLHS?".

>- strip all span-tags, all div-tags and all class-ids
>  in case one download this file for off-line browsing the *.css file
>gets lost.
Sam added .css file to the distribution (or put it in all clisp.cons directories where it was needed, I don't remember exactly) when I reported that problem here. So people can either
o download this .css file from where they found impnotes.html
o disable CSS (works in Netscape for me).

>- changed all Hyper-Spec online-links to local hard drive
>c:\hypers~1\...
That really needs customization :-)
This is done at install time for those who build CLISP from source.
Maybe there should be a small lisp program to do this at any time.
(defun change-impnotes-clhs-references (impnotes-file clhs-url) #)

Regards,
	Jorg Hohle.

---

From: Sam Steingold <[email-masked]>
Date: Thu May 22 07:07:04 2003

> * In message <[email-masked]>
> * On the subject of "[clisp-list] working on Implementations Notes layout"
> * Sent on Thu, 22 May 2003 09:39:21 +0200
> * Honorable "Hoehle, Joerg-Cyril" <[email-masked]> writes:
>
> I fear that you wasted some time working on .html. You'll probably
> have to learn about DSL, e.g. see doc/impnotes.dsl, which influences
> how impnotes.XML gets translated into impnotes.HTML, or you propose
> another way of turning docbook XML into html. I never looked into dsl
> myself.

forget DSSSL.
XSL is the way to go.
Note that impnotes in
<http://cvs2.cons.org/ftp-area/clisp/snapshots/impnotes/> and
<http://cvs2.cons.org/ftp-area/clisp/snapshots/impnotes.html>
are generated with XSL while the released version
<http://clisp.cons.org/impnotes.html> and
<http://clisp.cons.org/impnotes/>
are generated using DSSSL.

the framework is not yet in the CVS because I am also trying to get the
CLISP man page into Docbook/XML so that both groff and html version
would be generated from the same XML sources.

> I still have to learn docbook (and still am no friend, to say the
> least, of the verbosity of XML and thus docbook).

who is?!

> My personal opinion is also that there's a bit too much of
> cross-linking to CLHS. Every time e.g. CHARACTER appears in text, I
> see no need to have that link to CLHS.

think of the word CHARACTER as an object, with many properties (font,
bg, fg, link &c).  An object has the same properties everywhere.

> When I browse impnotes, I always have to check the status line to see
> "is this a link to another interesting section or is this yet another
> boring link to CLHS?".

When you read impnotes "from cover to cover", you can get used to the
extensive linking.

When you use it as a reference, you appreciate that every term in the
fragment you are interested in has an appropriate link.

> (defun change-impnotes-clhs-references (impnotes-file clhs-url) #)

1. change the entity &clhs; in cl-ent.xml to point to your favorite
   CLHS location.

2. regenerate clhs-ent.xml from the index file at that location using
   CLOCC/CLLIB/clhs.lisp (<http://www.podval.org/~sds/data/cllib.html>)

3. edit references in cl-ent.xml to &clhs; by hand.

-- 
Sam Steingold (http://www.podval.org/~sds) running RedHat9 GNU/Linux
<http://www.camera.org> <http://www.iris.org.il> <http://www.memri.org/>
<http://www.mideasttruth.com/> <http://www.palestine-central.com/links.html>
nobody's life, liberty or property are safe while the legislature is in session

---

From: LIN8080 <[email-masked]>
Date: Sun May 25 15:14:03 2003

"Hoehle, Joerg-Cyril" schrieb:
> So instead of improving mechanically generated HTML, I believe the only viable way is to change the transformation of XML (Docbook) into HTML. ...

> I fear that you wasted some time working on .html. You'll probably have to learn about DSL, e.g. see doc/impnotes.dsl, which influences how impnotes.XML gets translated into impnotes.HTML, or you p…

Aha. Now xml is like ??? for me, so I began to look around. First I read
some docs and this leads me to some questions.
ie: why using xml when sitting on an interpreter? or is it possible to
use the xml component svg (scalable vector graphics) and draw some lines
via a browser with cl? or what needs more time: to learn xml and do a
workthrough in docbooks or replace some details with a nice editor? hm.

Next I found some older zip files (01.03.00) named db152, db3x317,
dbx106, docbk31 and the imp-xml. Extracting this and take a closer look
- hey is that also generated stuff? (it looks like).
Anyway. I think I finished what I start (work inside the impnotes.html).
Meanwhile I have a look to learn something about creating dtds.

> o disable CSS (works in Netscape for me).

Ok. Thanks, found 2 css files. I write 3 lines into the head-section of
the html. Nice: I set all link text to size:11pt; (default is 12pt) and
text-decoration:none;. This removes the line under the link and the
mostly capital link-letters are a bit smaller (all links have different
color, thats enough). Now it is better readable (for me).

> (defun change-impnotes-clhs-references (impnotes-file clhs-url) #)
Great. Thats what I keep in mind.

---- Please check out: 
in section 1.4 in the overview ... 6 symbols missing ...(out of 978...)
is this number still ok? Or remove the number, otherwise update it every
time a new symbol is added.

on some places there is -td align="left"-, this is a default value and
can be removed. (maybe some exotic browsers need this?)

nearly 20 times there is the string '::=='. This is hardly visible in
the defaul font (Arial?). Also the ':' is not clearly in the text. For
my case I changed to the courier font, this looks ok (but there seems to
be a bug in Netscape 4.x: after every table-tag with -width="xx"- the
font-rules are gone and default is used. Please check this out)

stefan