development version newLISP 8.7.

[Lutz]

Regular expression mode for the 'directory' function, bug fixes, other novelties and a new indexed PDF version of the manual.



for files and changenotes see http://newlisp.org/downloads/development">http://newlisp.org/downloads/development



Lutz

[nigelbrown]

Hi Lutz,

I like the manual in pdf. Perhaps the pdf Contents could have active links into the manual body? Once in the body the cross-links work well.



Nigel

[Lutz]

Yes, that would be the best, but haven't found a free converter yet to do this. The manual posted is generated by loading the HTML version into OpenOffice 2.0, adding headers footers and generate table of contents from header-2 and header-3 tags, save as ODT format and using File/Export/PDF.



Lutz

[nigelbrown]

I'll look around for a way to do linked contents automatically.



Nigel

[nigelbrown]

Lutz,

Would you consider a Latex manual that could generate pdf and html?



Nigel

[Lutz]

What would be the advantages to the current approach?



Lutz

[nigelbrown]

Potentially you could have a single source that could generate multiple formats. the advantage over html to pdf would be more control over the pdf with the option of generating a paper format if desired. I'll look into whether there would be any loss in html quality ie if framed html can come from latex nicely.

I raised the possibility because I've not found a free pdf generator that does a linked contents.



I'll look into latex more as you didn't say no straight off.



Nigel

[Lutz]

The OpenOffice HTML->PDF conversion does a nice job maintaining formatting of headers and footers and does a nice job of buliding an index. The only thing really missing is linking, but anybody looking for that, can use the HTML version on a screen.



The PDF version is thought of a source for paper printing on 7x9 1/4.



Lutz

[cormullion]

In theory the best solution would be an XML-XSL-FOP solution, but it's all such a nightmare to install and configure that I just wouldn't wish it on anyone who had better things to do! But from there you could output to PDF and HTML with equal control (Apple are doing their developer documents this way now, Lutz).



Another Latex-like system is ConTeXt, again painful to install and get working but pretty good for PDF/HTML generation, and ideal for large documents such as manuals. I'd recommend it over LaTeX, once you've got LaTeX installed.



I'd be happy to do the whole thing in Adobe FrameMaker for you... just ask!



Perhaps someone should write a newLISP app to output PDF from HTML. It can't be that difficult...!

[Lutz]

... very interesting. What is it you think we are missing from the formatting of the current PDF?



In my opinion the only thing is better page breaks. Sometimes things are separated where they shouldn't. OpenOffice offers orphan control, paragraph-keep-with-next, etc., but very often it is not what you want and it has to be hand edited anyway.



Is there stuff in Latex and/or FrameMaker doing this better in an automated fashion?



How would the whole situation look like if one decides to self-publish a printed newLISP manual.



Is the current formatting (plus a manual pass for better page breaks) acceptable? What would we need to make it really professional looking? Is the quality of the English acceptable? Does it need a professional editor (like you ;) ) ? Do people accept PDFs or PostScript for printing? Or does it have to be Latex or FrameMaker?



I never had so many questions in one post ;)



Lutz

[cormullion]

Heh - the only reason I contributed to this thread is because I know something about it. I don't have any criticisms of the newLISP documentation! :-)



The documentation for newLISP is generally excellent - I use the HTML version both to read, and from within newLISP itself, as you know, using a macro function. I don't use the PDF at all - because the links aren't clickable... The text could probably do with some spell-checking and a few stylistic tweaks, but apart from that, I'm very happy with the HTML.

Is there stuff in Latex and/or FrameMaker doing this better in an automated fashion?

Both Latex and FrameMaker can be used to produce the printed books you see in the bookshops, and both automatic and manual adjustments can be made to make the document aesthetically pleasing to look at (or close enough, where LaTeX is concerned :-)). Few professional books will be output without any manual tweaking at all, though. The books produced by O'Reilly etc., and the manuals produced by Microsoft/Adobe, etc, will probably be done in InDesign, Quark, or Frame, and rendered to PDF. These DTP products will also - in addition - be able to produce useful (cross-referenced and clickable) PDFs for online distribution and viewing, as a side effect. I've seen fewer LaTeX books - mainly in the Mathematics sections...

How would the whole situation look like if one decides to self-publish a printed newLISP manual.

You could use either LaTeX or a DTP package. However, you're unlikely to be able to produce a formatted-for-print manual starting with an HTML original that will compare well with O'Reilly's offerings.

Is the current formatting (plus a manual pass for better page breaks) acceptable? What would we need to make it really professional looking? Is the quality of the English acceptable? Does it need a professional editor (like you ;) ) ? Do people accept PDFs or PostScript for printing? Or does it have to be Latex or FrameMaker?

Answers: Acceptable for my private online use yes. Professional books are designed by professionals on DTP systems such as InDesign/Quark/FrameMaker. But you would lose the ability to write and edit collaboratively at no cost - which you can do with a TeX-based solution. I don't think LaTeX manuals look very professional, a lot of the time, compared with DTP ones. Most print shops accept PDFs for printing, and wouldn't want to see LaTeX, Frame, or even Quark/DTP source files.



I'm happy to help out the newLISP documentation effort. But there are plenty of 'interesting' practical issues to resolve!

[eddier]

Lutz,



I would be glad to generate the documentation from LaTeX. I've been using LaTeX for quite some time now and the PDF links and such are no problem at all.



I could generate a copy by next week and e-mail it to you to look at and see if you like it?



Eddie

[Lutz]

Yes Eddie, thanks!



Lutz

[eddier]

I should be able to do it over the weekend.



Eddie

[nigelbrown]

Hi Eddie,

I'm pleased you have the skills for latex, while I raised it as an option I don't have the experience you have.

I look forward to seeing the text, a well set manual can be a thing of beauty in itself.



Nigel