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
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
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
I'll look around for a way to do linked contents automatically.
Nigel
Lutz,
Would you consider a Latex manual that could generate pdf and html?
Nigel
What would be the advantages to the current approach?
Lutz
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
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
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...!
... 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
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.
Quote from: "Lutz"
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...
Quote from: "Lutz"
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.
Quote from: "Lutz"
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!
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
Yes Eddie, thanks!
Lutz
I should be able to do it over the weekend.
Eddie
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
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
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
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
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
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
Actually, what I was thinking: create a file called manual.txt. Run the script
./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
.h 0 Introduction
.p this is a paragraph
.h 1 Section One
.h 2 Subsection
...
=>
<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
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
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
Quote
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]
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!
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/newlisp/newlisp_manual.pdf and http://users.cyberone.com.au/nbrown/newlisp/newlisp_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/~schectex/wincd/list_tex.htm for good software links.
Nigel
Will Nigel's solution work Lutz? If it does I would like to make one suggestion. In the .tex file on the very next line after the documentclass{article
usepackage{newcent}
This will make the fonts much cleaner and enable you to copy and paste text from the manual (if you click the [T] button on the toolbar).
Eddie
Hi Eddie,
I tried putting in usepackage{newcent} in but it didn't change much - there possibly is something that needs to come out to let the package work. I tried taking out amsfonts but that didn't help. Anyone know the trick?
The pdf was a first try so perhaps changing use of styles, and by that fonts, in openoffice may help. Also in the long run letting latex do more and generating html and pdf etc from that may be the cleanest approach. Once a tidy latex file is achieved then Lyx may well import it cleanly and thus Lyx could be used as a friendlier editor.
Nigel
If you can, show all of the stuff between documentclass{.... and begin{document}. Another suggestion is the ordering of the packages: try putting usepackage{newcent} as the last package before begin{document}
Eddie
Posted: http://users.cyberone.com.au/nbrown/newlisp/newlisp_manual.tex
which is made by doing:
C:writer2latex04>w2l.bat newlisp_manual.sxw
This is Writer2LaTeX, Version 0.4 (2005-07-01)
Starting conversion...
Done!
C:writer2latex04>
Then loading as file into TexNicCenter and doing search&replace of newline to nothing (ie delete newline). This would remove a few valid formatting newlines but is a quick hack.
The .tex file upto begin{document} is :
% This file was converted to LaTeX by Writer2LaTeX ver. 0.4
% see http://www.hj-gym.dk/~hj/writer2latex for more info
documentclass[12pt,twoside]{article}
usepackage[ascii]{inputenc}
usepackage[T1]{fontenc}
usepackage[english]{babel}
usepackage{amsmath,amssymb,amsfonts,textcomp}
usepackage{color}
usepackage{calc}
usepackage{longtable}
usepackage{hyperref}
hypersetup{colorlinks=true, linkcolor=blue, filecolor=blue, pagecolor=blue, urlcolor=blue}
% Text styles
newcommandtextstyleTeletype[1]{textrm{#1}}
newcommandtextstyleSourceText[1]{texttt{#1}}
% Outline numbering
setcounter{secnumdepth}{0}
% List styles
newcommandliststyleLii{%
renewcommandtheenumi{arabic{enumi}}
renewcommandlabelenumi{theenumi.}
renewcommandlabelitemi{{textbullet}}
renewcommandlabelitemii{{textbullet}}
renewcommandlabelitemiii{{textbullet}}
}
newcommandliststyleLiii{%
renewcommandtheenumi{arabic{enumi}}
renewcommandlabelenumi{theenumi.}
renewcommandlabelitemi{{textbullet}}
renewcommandlabelitemii{{textbullet}}
renewcommandlabelitemiii{{textbullet}}
}
newcommandliststyleLiv{%
renewcommandlabelitemi{{textbullet}}
renewcommandlabelitemii{{textbullet}}
renewcommandlabelitemiii{{textbullet}}
renewcommandlabelitemiv{{textbullet}}
}
newcommandliststyleLv{%
renewcommandtheenumi{arabic{enumi}}
renewcommandtheenumii{arabic{enumii}}
renewcommandtheenumiii{arabic{enumiii}}
renewcommandtheenumiv{arabic{enumiv}}
renewcommandlabelenumi{theenumi.}
renewcommandlabelenumii{theenumii.}
renewcommandlabelenumiii{theenumiii.}
renewcommandlabelenumiv{theenumiv.}
}
newcommandliststyleLvi{%
renewcommandtheenumi{arabic{enumi}}
renewcommandtheenumii{arabic{enumii}}
renewcommandtheenumiii{arabic{enumiii}}
renewcommandtheenumiv{arabic{enumiv}}
renewcommandlabelenumi{theenumi.}
renewcommandlabelenumii{theenumii.}
renewcommandlabelenumiii{theenumiii.}
renewcommandlabelenumiv{theenumiv.}
}
newcommandliststyleLvii{%
renewcommandlabelitemi{{textbullet}}
renewcommandlabelitemii{{textbullet}}
renewcommandlabelitemiii{{textbullet}}
renewcommandlabelitemiv{{textbullet}}
}
% Pages styles (master pages)
makeatletter
newcommandps@HTML{%
renewcommand@oddhead{}%
renewcommand@evenhead{}%
renewcommand@oddfoot{}%
renewcommand@evenfoot{}%
setlengthpaperwidth{20.999cm}setlengthpaperheight{29.699cm}setlengthvoffset{-1in}setlengthhoffset{-1in}setlengthtopmargin{1cm}setlengthheadheight{12pt}setlengthheadsep{0cm}setlengthfootskip{12pt+0cm}setlengthtextheight{29.699cm-1cm-1cm-0cm-12pt-0cm-12pt}setlengthoddsidemargin{2cm}setlengthtextwidth{20.999cm-2cm-1cm}
renewcommandthepage{arabic{page}}
setlength{skipfootins}{0.101cm}renewcommandfootnoterule{vspace*{-0.018cm}noindenttextcolor{black}{rule{0.25columnwidth}{0.018cm}}vspace*{0.101cm}}
}
makeatother
pagestyle{HTML}
setlengthtabcolsep{1mm}
renewcommandarraystretch{1.3}
title{newLISP v8.7.1 Manual and Reference}
begin{document}
Nigel
I don't see any problems except that it is not loading the newcentury fonts.
You can kill the usepackage[ascii]{inputenc} and usepackage[T1]{fontenc} if you wish.
I even doubt wether you need the usepackage{amsmath,amssymb,amsfonts,textcomp} since I don't think there's probably any serious math stuff going on in the manual. I have never had any font troubles with these packages except for textcomp. I'm not sure what that one does.
add
usepackage{newcent}
where it will read
title{newLISP v8.7.1 Manual and Reference}
usepackage{newcent}
begin{document}
Now, pdflatex newlisp_manual.tex twice.
The first pass gets the information for the table of contents and the links
The second pass will put that information back into the pdf file.
The text shown in acrobat should be clean and copyable.
Eddie
Hi Eddie,
I found it worked putting it here:
renewcommandlabelitemiv{{textbullet}}
}
usepackage{newcent}
% Pages styles (master pages)
makeatletter
The font is much clearer. Thanks!
see
http://users.cyberone.com.au/nbrown/newlisp/newlisp_manual-newcent.pdf
Putting it between title and begin lost the Table of Contents.
I commented out: %usepackage[ascii]{inputenc} OK but
commenting out usepackage[T1]{fontenc} caused lots of error regarding textquotedbl
commenting out usepackage{amsmath,amssymb,amsfonts,textcomp} causes errors re textquotesingle.
The updated .tex reads now:
% This file was converted to LaTeX by Writer2LaTeX ver. 0.4
% see http://www.hj-gym.dk/~hj/writer2latex for more info
documentclass[12pt,twoside]{article}
%usepackage[ascii]{inputenc}
usepackage[T1]{fontenc}
usepackage[english]{babel}
usepackage{amsmath,amssymb,amsfonts,textcomp}
usepackage{color}
usepackage{calc}
usepackage{longtable}
usepackage{hyperref}
hypersetup{colorlinks=true, linkcolor=blue, filecolor=blue, pagecolor=blue, urlcolor=blue}
% Text styles
newcommandtextstyleTeletype[1]{textrm{#1}}
newcommandtextstyleSourceText[1]{texttt{#1}}
% Outline numbering
setcounter{secnumdepth}{0}
% List styles
newcommandliststyleLii{%
renewcommandtheenumi{arabic{enumi}}
renewcommandlabelenumi{theenumi.}
renewcommandlabelitemi{{textbullet}}
renewcommandlabelitemii{{textbullet}}
renewcommandlabelitemiii{{textbullet}}
}
newcommandliststyleLiii{%
renewcommandtheenumi{arabic{enumi}}
renewcommandlabelenumi{theenumi.}
renewcommandlabelitemi{{textbullet}}
renewcommandlabelitemii{{textbullet}}
renewcommandlabelitemiii{{textbullet}}
}
newcommandliststyleLiv{%
renewcommandlabelitemi{{textbullet}}
renewcommandlabelitemii{{textbullet}}
renewcommandlabelitemiii{{textbullet}}
renewcommandlabelitemiv{{textbullet}}
}
newcommandliststyleLv{%
renewcommandtheenumi{arabic{enumi}}
renewcommandtheenumii{arabic{enumii}}
renewcommandtheenumiii{arabic{enumiii}}
renewcommandtheenumiv{arabic{enumiv}}
renewcommandlabelenumi{theenumi.}
renewcommandlabelenumii{theenumii.}
renewcommandlabelenumiii{theenumiii.}
renewcommandlabelenumiv{theenumiv.}
}
newcommandliststyleLvi{%
renewcommandtheenumi{arabic{enumi}}
renewcommandtheenumii{arabic{enumii}}
renewcommandtheenumiii{arabic{enumiii}}
renewcommandtheenumiv{arabic{enumiv}}
renewcommandlabelenumi{theenumi.}
renewcommandlabelenumii{theenumii.}
renewcommandlabelenumiii{theenumiii.}
renewcommandlabelenumiv{theenumiv.}
}
newcommandliststyleLvii{%
renewcommandlabelitemi{{textbullet}}
renewcommandlabelitemii{{textbullet}}
renewcommandlabelitemiii{{textbullet}}
renewcommandlabelitemiv{{textbullet}}
}
usepackage{newcent}
% Pages styles (master pages)
makeatletter
newcommandps@HTML{%
renewcommand@oddhead{}%
renewcommand@evenhead{}%
renewcommand@oddfoot{}%
renewcommand@evenfoot{}%
setlengthpaperwidth{20.999cm}setlengthpaperheight{29.699cm}setlengthvoffset{-1in}setlengthhoffset{-1in}setlengthtopmargin{1cm}setlengthheadheight{12pt}setlengthheadsep{0cm}setlengthfootskip{12pt+0cm}setlengthtextheight{29.699cm-1cm-1cm-0cm-12pt-0cm-12pt}setlengthoddsidemargin{2cm}setlengthtextwidth{20.999cm-2cm-1cm}
renewcommandthepage{arabic{page}}
setlength{skipfootins}{0.101cm}renewcommandfootnoterule{vspace*{-0.018cm}noindenttextcolor{black}{rule{0.25columnwidth}{0.018cm}}vspace*{0.101cm}}
}
makeatother
pagestyle{HTML}
setlengthtabcolsep{1mm}
renewcommandarraystretch{1.3}
title{newLISP v8.7.1 Manual and Reference}
begin{document}
Latex still doesn't like the GPL formatting at the end - it uses a fancy table but the construct as is throws an error. I note near the end of conversion writer2latex gives an 'out of memory' error but continues and still does a reasonable job - obviously tweaking is in order.
Maybe a newlisp program to replace the html constructs in the html manual with latex format commands and then wrapping that in a latex style is the newlisp way to go! (imagine relying on java to do the newlisp manual). I'll add html2latex.lsp to my list of possible projects.
Nigel
Hi Nigel,
Looks great! Strange that it lost the table of contents.
Quote
commenting out usepackage{amsmath,amssymb,amsfonts,textcomp} causes errors re textquotesingle.
I'm not sure why they do it that way? Maybe to avoid useing backquotes. In latex, the left single quote is ` and the left double quote is `` two of them. Yep I bet you got small black rectangle for double quotes when you commented them out no?
Quote
Sounds like a fun project!
I worked on a translator for document codes into both html and latex for a little. I plan to work on this some more after I have finished the college's IT Plan. Even if not for newLISP but for creating large documents at work.
Eddie
The last PDF is very impressive! Very nice fonts, easy to the eyes. The PDF reads perfectly OK in Linux with Xpdf 3.01, including the hyperlinks.
Regards and thanks
Peter
I'm glad you like it Peter, Thanks for the help Eddie.
By the way, the cyberone servers (the ISP I use) seems to have gone down tonight for anyone trying to get the pdfs - I don't know if they are just changing their IP address and it is taking time for the DNS to propogate as I'm getting 'failure to resolve' errors but can access other sites.
Nigel
I'm posting some comments on newlisp_manual html tags on doc thread http://www.alh.net/newlisp/phpbb/viewtopic.php?p=5633#5633 .
They may help conversion to latex.
Nigel