Introduction to newLISP updated for 9.4

[Lutz]

Thanks to Cormullion from



http://unbalanced-parentheses.nfshost.com/index.cgi">http://unbalanced-parentheses.nfshost.com/index.cgi



an updated version of the popular "Introduction to newLISP" is online here:



http://www.newlisp.org/introduction-to-newlisp.pdf">http://www.newlisp.org/introduction-to-newlisp.pdf  in PDF format

http://www.newlisp.org/introduction-to-newlisp.html">http://www.newlisp.org/introduction-to-newlisp.html in HTML format



a must read for all newbies

[hsmyers]

Excellent! Can't have too much documentation about a computer language— more is always better. Cormullion, a job well done, thank you!



--hsm

[DrDave]

Cormullion,



Thanks for all your hard work at keeping the introdution up to date.



I haven't actually read the entire doc yet, but a quick run through it brings up the following items.



I downloaded both the PDF and HTML versions. Unfortunatelhy, you coded the images for the HTML for on-line viewing, resulting in just an image placeholder when viewing the downloaded HTML.



Of course, I can open the HTML online and then save it as MHT in order to get the images, but I really prefer to save as HTML. I shouldn't have to be concerned about all this; I should be able to do download directly from the link as well as open online and save as HTML and get the images without resorting to MHT.



You put nice captions on the images in the PDF file, but I don't see any captions at all in the HTML version.



It appears to me that you must have used different source files for the two versions. I thought the MAC has document composing apps that enable a single source doc to be output in multiple document types. I don't have a problem on WINDOWS platform using MS Word source and saving as HTML (admittedly bloated HTML) as well as converting the Word file to PDF with Distiller (or even freeware PDF makers). Or I can compose in LyX and output as PDF, Latex, whatever.



Also, I rather like the various color codings you've implemented in the HTML doc and wonder why you didn't use the same ones in the PDF as well.



I see in the PDF that when you use "$IDX" (as well as all other words you wrap in <code> tags) it is bold and a much larger font size (really too large) than the surrounding text. Maybe your <code> tag needs a revised definition in the style sheet? $idx looks OK as far as size in the PDF, but a different color would be better.



In paragraph 4.8.2, most of the unicode symbols do not display for me (Internet Explorer 6.0 and 7.0). I checked the encoding and it is set for UTF-8, so I tried setting to other encodings with no difference. If I copy-and-paste (or open the MHT) into Word, all of the symbols display correctly. If I then save this correctly displayed section as HTML, it opens and displays the symbols correctly in Internet Explorer.

[Lutz]

Generating PDF and HTML from one format sounds easier than it is. Even using good tools you never really succeed. The devil is in the detail and needs lot of manual intervention.



Here is my experience with the newLISP Users Manual and Reference:



It is a long story of almost half a day to go from HTML to PDF using a tool-chain of text transforming newLISP scripts and NeoOffice (Open Office for the Mac) with customized translation of the different tags/styles found in the HTML document.



To make it short: there is no automated way to do format and layout translation. Each format has its own requirements and in the end needs manual intervention.



Most important: they should not look alike! Each format has its own purpose. The book/PDF format is a fixed layout format, mosy likely to be printed to be read from paper. You want more whitespace and more sophisticated formatting with correct page breaks etc. The HTML format should be more dense, but flow well in different window sizes etc., it is read from a computer monitor, most likely on-line.

[cormullion]

Hi there! It's an imperfect world, isn't it! :)

I haven't actually read the entire doc yet, but a quick run through it brings up the following items.



I downloaded both the PDF and HTML versions. Unfortunatelhy, you coded the images for the HTML for on-line viewing, resulting in just an image placeholder when viewing the downloaded HTML.



Of course, I can open the HTML online and then save it as MHT in order to get the images, but I really prefer to save as HTML. I shouldn't have to be concerned about all this; I should be able to do download directly from the link as well as open online and save as HTML and get the images without resorting to MHT.

Actually the story behind the HTML version is that someone wanted it in HTML (and did their own translation no less) rather than PDF (which is the only format I wanted to generate) and I thought it would be cool to do HTML at the same time as the PDF, provided that it was no extra work. I make a web archive of most of the HTML documents that I use offline, and I suppose that's what you do too.



I hadn't thought about downloading it and using it offline other than in a web archive, so I could probably alter things so that the images are relative. Then it could all be zipped up and downloaded. (More work, so it wouldn't be done soon...)



The other thing behind the HTML version was that you can use your own CSS style file (I think - haven't tested that recently) - just put it in the same location and it should pick it up. That way, you can play with all the fonts and colours to get them to your taste.

You put nice captions on the images in the PDF file, but I don't see any captions at all in the HTML version.

True. The numbering schemes are very different generally. I like to think the format dictates some of the layout requirements...

It appears to me that you must have used different source files for the two versions. I thought the MAC has document composing apps that enable a single source doc to be output in multiple document types. I don't have a problem on WINDOWS platform using MS Word source and saving as HTML (admittedly bloated HTML) as well as converting the Word file to PDF with Distiller (or even freeware PDF makers). Or I can compose in LyX and output as PDF, Latex, whatever.

No, there's only one source document. But the translator is a bit psycho. :)

Also, I rather like the various color codings you've implemented in the HTML doc and wonder why you didn't use the same ones in the PDF as well.

When you print them out any shading makes the text difficult to read. But without shading it still looks OK. I'm thinking PDF->paper, HTML->screen (call me old-fashioned!).

I see in the PDF that when you use "$IDX" (as well as all other words you wrap in <code> tags) it is bold and a much larger font size (really too large) than the surrounding text. Maybe your <code> tag needs a revised definition in the style sheet? $idx looks OK as far as size in the PDF, but a different color would be better.

Do you mean in the HTML? It looks OK to me, and you can change it anyway when it's local on your machine.

In paragraph 4.8.2, most of the unicode symbols do not display for me (Internet Explorer 6.0 and 7.0). I checked the encoding and it is set for UTF-8, so I tried setting to other encodings with no difference. If I copy-and-paste (or open the MHT) into Word, all of the symbols display correctly. If I then save this correctly displayed section as HTML, it opens and displays the symbols correctly in Internet Explorer.

Dunno. Outside my comfort zone! The Unicode symbols were a real pain to get right in both versions even on one platform. I don't test with Internet Explorer.



And thanks for reading them! Feel free to email me if you find mistakes and typos (there are lots of each!).

[DrDave]

Generating PDF and HTML from one format sounds easier than it is. Even using good tools you never really succeed. The devil is in the detail and needs lot of manual intervention.

Maybe you don't have the right tools and sufficient experience? Afterall, your expertise is programming, not document formatting.



Speaking now with my technical writer's hat on, I can essentially duplicate the HTML document by saving in HTML format from MS Word 2003 native DOC format. I can also convert that DOC file to PDF either by "printing" to an installed PDF maker, or by using Distiller.



All of the currently used styles for coloring, paragraph backgorunds, etc., can be either duplicated, or come extremely close to the current document.



The PDF as-is doesn't have the links working for the table of contents so would need some "manual intervention" to remedy that. (Although I have an idea to try in the source DOC that might eliminate the need to manually tweak the PDF.)



The HTML could also be "improved" a bit by having the unused white space on the left (all of it under the TOC links) usable instead of blank, and also the body text right margin will float. Currently, when I resize the HTML file, the right margin for the text is fixed. My version will have that dynamically change as the window size is changed.



Although the idea that HTML and PDF are expected to have a different "look and feel" because the formats were developed for different purposes is widespread, is it really applicable here? The PDF *probably*, but not necessarily, will give a bit nicer looking output on a printed page. But if the source document were to be set up originally for printed output and then saved as HTML, there would be very little diffrence when printed compared with the PDF version. Of course viewing on the computer screen would be slightly different if dynamic right margins are used in the HTML.

[Lutz]

The PDF as-is doesn't have the links working for the table of contents

Do not view the PDF file in a web browser.



If you download the newlisp_manual.pdf file and view with either the Adobe Acrobat viewer on MS Windows or the built-in Preview App. on Mac OS X, you get a clickable index in the sidebar of the reader or viewer, and the hyperlinks inside the text work too. The expandable/collapsable index in the sidebar will never go away and it makes it easy to navigate in the manual.

[DrDave]

Hi there! It's an imperfect world, isn't it! :)

Yes, quite! But I suppose it would become a rather boring world if everything were perfect. But it is nice to have a forum like this one where people are willing to help out to improve things, more like the original hacker ethic("Hackers", Steven Levy).



OK, I understand now why the HTML and PDF look quite a bit different.



Even though the style sheet approach does enable the enduser to tweak displayed settings, in general, it tends to be simpler to avoid style sheets. But if they are used, I've found it is much easier to create the source document in a word procesor and apply colors, shadings, and styles that will be generic enough to look OK both on-screen and printed on white paper. (yes, I know on-screen and on white paper *should* be done with essentially reversed color schemes: dark text on light background (black on white preferred) for paper, light text on dark background (orange-yellow on Navy blue preferred) for on-screen. I'm still subjected to some of those  horrendous PowerPoint slides with colors like red text on blue backgorund or yellow text on white background that were invented by mind-control experts to break you by the most efficient means known to modern man!



As for the $idx display problem (and every other text wrapped in <code> tags), yes, it was just in the HTML that it is oversized. It is OK in the PDF.



As for the problem with the unicode characters not displaying in Internet Explorer, I'll copy them to another document and save as HTML and send it to you so you can see if it displays in your browser(s), and see if the code is any differnt than what you started with.

[cormullion]

code font size: I see that Safari computes the font-size as 16, but Opera and Firefox both compute it as 19, so it might be better to drop a size and have it a smidgeon on the small side for Safari. Consider it done for the next release. :)



unicode: it could be a font-related problem. I'm not the one to ask...