development version newLISP 8.7.

Lutz · Post by **Lutz** » Sun Jan 08, 2006 11:28 pm

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

Lutz

nigelbrown · Post by **nigelbrown** » Mon Jan 09, 2006 12:54 am

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 · Post by **Lutz** » Mon Jan 09, 2006 2:16 am

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 · Post by **nigelbrown** » Mon Jan 09, 2006 3:18 am

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

Nigel

nigelbrown · Post by **nigelbrown** » Wed Jan 18, 2006 12:01 pm

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

Nigel

Lutz · Post by **Lutz** » Wed Jan 18, 2006 1:37 pm

What would be the advantages to the current approach?

Lutz

nigelbrown · Post by **nigelbrown** » Wed Jan 18, 2006 2:18 pm

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 · Post by **Lutz** » Wed Jan 18, 2006 2:52 pm

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 · Post by **cormullion** » Wed Jan 18, 2006 4:19 pm

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 · Post by **Lutz** » Wed Jan 18, 2006 5:26 pm

... 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 · Post by **cormullion** » Wed Jan 18, 2006 7:12 pm

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.

Lutz wrote: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...

Lutz wrote: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.

Lutz wrote: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 · Post by **eddier** » Thu Jan 19, 2006 1:09 pm

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 · Post by **Lutz** » Thu Jan 19, 2006 3:23 pm

Yes Eddie, thanks!

Lutz

eddier · Post by **eddier** » Thu Jan 19, 2006 3:47 pm

I should be able to do it over the weekend.

Eddie

nigelbrown · Post by **nigelbrown** » Thu Jan 19, 2006 10:38 pm

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

eddier · Post by **eddier** » Mon Jan 23, 2006 2:35 pm

Nigel,

I somewhat cheat on this. There is generally a package of macros to do about anything you want in LaTeX. I don't write that many macros (depends on the project). I just \usepackage{whatever} and use the commands from the manual provided. I also use LyX many times to get the main content in and then export the latex to tweak. I have written some tools usually in Python or newLISP to generate graphs in the {epic,eepic} picture environment, which is pretty easy.

Lutz,

This is going to take longer than I thought. Even when replacing HTML codes with LaTeX codes using the regular expression replacement in emacs, it is going to take some time. Also, the structure of the manual doesn't really match the structure of a document imposed by LaTeX. I worked on it a bit Friday night until the wife and I had to babysit our two year old granddaughter. Last night I start on a Quick Reference. After I complete a quick reference, I'll go back and tackle the main document which is now much bigger than I remember. I'm going to need more time on this than I previously thought.

Eddie

Lutz · Post by **Lutz** » Mon Jan 23, 2006 4:06 pm

Don't stress, the PDF manual we have does a good job and is really made for printing 7x9 hard copies. On the computer people should use the hyperlinked HTML docs.

Of course if all that work results in a script I just have to run to get HTML and PDF than it is worth it and perhaps even faster than what I am doing now. But it would be too much if for every manual we would have to tweak stuff.

Lutz

eddier · Post by **eddier** » Mon Jan 23, 2006 4:26 pm

Actually a script to generate both the HTML version and a PDF file is what I would prefer doing. I'm doing something similar to this for the Factbook I generate here at the College. If I make this script, could we possibly generate two PDF documents instead of one (One for the main document and the other of a Quick Reference)? The reason is that parts, chapters, sections, and subsections are added to both the Bookmarks of a PDF file and the Table of Contents.

Eddie

Lutz · Post by **Lutz** » Mon Jan 23, 2006 5:24 pm

A quick reference sounds like a good idea, having all functions with calling signatures on one sheet. Once the script works I would edit the LaTex file directlly when adding/modifying content? What would I need on the MacOS X to run the script? Or is that stuff already default/UNIX installed. It could also be FreeBSD which is my ISP shell-account.

Lutz

eddier · Post by **eddier** » Mon Jan 23, 2006 5:34 pm

Are you using OSX?

If you are using Linux, the PDF and HTML files generated by the script would be portable across all platforms.

Eddie

eddier · Post by **eddier** » Mon Jan 23, 2006 5:49 pm

Actually, what I was thinking: create a file called manual.txt. Run the script

Code: Select all

./doc.lsp quickref.txt

The output would be 3 files: "manual.html," "manual.pdf," and "qref.pdf." This might actually take a bit more thought?

We would just use short commands in manual.txt

Code: Select all

.h 0 Introduction
.p this is a paragraph
.h 1 Section One
.h 2 Subsection
...

=>

Code: Select all

<html>
<head>
<title>manual</title>
<style>
 ...
</style>
</head>
<body>
<h1>Contents</h1>
<ol type="I">
  <li>Introduction</li>
  <li>Section One</li>
...
</ol>
<p style="newpage">
<h1>Introduction</h1>
<p>this is a paragraph</p>
<h2>Section One</h2>
...

and

Code: Select all

\documentclass{article}
\usepackage{newcent}
\usepackage[hyperref stuff ...]{hyperref}
\usepackage[margin=1in]{geometry}
...
\begin{document}
\tableofcontents
\newpage
\chapter{Introduction}

this is a pragraph

\section{Section One}

...

We just need to define what codes we would need. Especially for the inline code sections. This is the reason I suggest building the quick reference first, to determine what codes we should have.

Eddie

Lutz · Post by **Lutz** » Mon Jan 23, 2006 8:27 pm

If the only thing we gain is links in the PDF file than that looks like a lot of work and not worth it, thinking that hyperlinks are for computer viewing via HTML and PSF is for printing?

Editing a text file would be fine, as long as everything we do is with standard tools. I do not want add new dependencies, incompatibilities etc.. The current method using HTML and OpenOffcie at least works on all platforms. We will do it but is has to be simple.

Lutz

eddier · Post by **eddier** » Mon Jan 23, 2006 11:22 pm

Editing a text file would be fine, as long as everything we do is with standard tools. I do not want add new dependencies, incompatibilities etc.. The current method using HTML and OpenOffcie at least works on all platforms. We will do it but is has to be simple.

By all means! The standard tools would be pdflatex, newlisp, and a text editor. Chances are pdflatex, newlisp, and a text editor are already on your machine ;)

Actually, this is very similar to a project I'm currently working on. So the lessons will carry from one project to the other. If no one minds, It'll take some time though.

Eddie[/quote]

cormullion · Post by **cormullion** » Tue Jan 24, 2006 10:16 am

I'm following this topic with great interest - I'd like to contribute somehow... Currently, though, I've been unable to install LaTeX on my machine (downloads are too big), so I may be of little use. But ask for any help anyway!

nigelbrown · Post by **nigelbrown** » Wed Jan 25, 2006 6:16 am

Hi all,
I've had some success generating a pdf with a hyperlinked Table of Contents using this tool chain:

1) import html manual into openoffice (2.0), save working file in openoffice format
2) generate a table of contents with included hyperlinks using openoffice functionality with hyperlink referencing selected
3) save this file as openoffice 1 format eg .sxw

4)here instead of using pdf output from openoffice I use Writer2Latex to generate a .tex file from the .sxw file - see http://www.hj-gym.dk/~hj/writer2latex/

5) open .tex file in TeXnicCenter (see http://www.texniccenter.org/front_content.php?idcat=50 - friendly but close to the bone if you want), removed all the /newline with text search and replace (were giving latex a problem) and click 'build and view current file' button to see the pdf (ignore the errors from latex engine the pdf opens and looks "OK").

The pdf (1,344 kB) does show some tweaking is needed eg trademark symbol, some font sizes are too big and cause wrapping in the syntax definitions etc but the hyperlinked table of contents is what I was looking for.

I'll put this first try pdf up for viewing for anyone interested - I've uploaded the pdf and sxw files to http://users.cyberone.com.au/nbrown/new ... manual.pdf and http://users.cyberone.com.au/nbrown/new ... manual.sxw .

Hope this may help. I tried Lyx before TeXnicCenter to import .tex but the relyx import process gave problems. I tried html2latex.c but it would need a tweaked definition file to get the html manual version in properly.
See http://www.math.vanderbilt.edu/~schecte ... st_tex.htm for good software links.

Nigel