The l2h help pages |
|
© Leon van Dommelen |
|
The latest version of this document is online at
eng.famu.fsu.edu or at
dommelen.net.
How to get started
WARNINGS: Please Read
There is no warranty of any kind on this free software.
There are copyrights by various authors.
To help avoid possible loss of your data, follow the next
rules:
- Do not put files that have an "@" character in their name in your
document folder. L2h assumes that it can do whatever it wants with
such files.
- Similarly, leave the "@system" subfolder alone.
- In addition, file index.html may be modified during web page
creation. (Though probably not if it is your own file.)
- Any file .latex2html-init will routinely get clobbered. For l2h,
you should edit settings.pl instead.
- If you need to put files in the "web-pages" folder, place them
inside its subfolder "keep". Or they will in fact disappear.
- Do not delete files anywhere inside the l2h folder. If l2h sees
that any file it may need to operate has disappeared, it will drop
everything and abort.
You really should always keep backups of files you put in l2h folders.
Installation
If you are reading this, you probably already finished installation.
Otherwise:
Note that whenever you move l2h elsewhere, (which you should avoid
doing if possible), or your latex, ghostscript, or perl changes
location in MS Windows, you must rerun install_l2h. Before doing
so, exit all other l2h windows. (If you do move l2h, afterwards you
will also need to update all document folders outside l2h that you are
still working on. To update a document folder, replace the "l2h_menu"
file in it by a copy of the updated one in the "example"
folder of l2h.)
Quick-Start Guide
Note: This guide assumes that you are using l2h through a
graphical user interface (GUI) that allows you to click files in
folders and such. If you have no GUI, like when you are using "Putty"
or "ssh" to access a remote computer,
see nonGUI.html for how to compensate.
-
Find the l2h folder, then the "example" subfolder in it. Create a
copy of this example folder elsewhere. To do so, right-click
"example" and select "copy" (not cut). Then right-click
inside your Documents folder, or maybe simply on your desktop and
select "Paste" (not "Paste Shortcut"). Now right-click the
just pasted folder and select "Rename" (or maybe "Properties".)
Change the folder name from "example" into "document_1", "my_thesis",
or something else meaningful to you. Note that spaces in the name are
OK as far as l2h is concerned. But other software may not like them,
so I prefer underscores, lowercase letters, and digits only. For
example, if you have both a folder "My_Thesis" and a folder
"my_thesis" in Unix, disaster will strike when you add any Microsoft
component to the mix. Trust me. From now on, I will assume that you
renamed the copied folder to "document_1". If not, substitute your
own name.
- Security warning: l2h will set protections to make the
generated pdf and web-pages versions of the document readable to
world. If this is not desired, be sure to place the copied example
folder inside a folder that offers no access to world.
-
Open folder document_1 by double-clicking it. Inside, there is an icon
"l2h_menu". Double click it; a new window will open.
-
Linux users only: The window is supposed to be big enough for
24 lines of 80 characters each. That is the standard for terminal
windows. However, my Ubuntu 12.04 with gnome-session-fallback will
not do so. I need to go into the "Terminal" menu and manually select
80x24. Afterwards I have to hit the "-" key to get the screen to
respond again. Do not hit another key before hitting "-". It is also
recommended that you enable the terminal bell. See the installation
instructions.
-
You will be asked to select an example document. Read the description
and then press the key of the desired choice. However, at this time
use choices 1 through 4, not 5 through 8. You want to test
your installation first. The example will be copied into the
document_1 folder with the name "index.tex". For more information on
the examples, and to see how the resulting documents may look, see
the examples.html web page.
-
You will normally be given a choice of editors with which to open the
selected example. If not, open file "index.tex", in the document_1
folder, with a text editor manually. Right-clicking the file should
give some suitable option. If that does not work either, open a text
editor like Notepad or gedit and browse down to the just created
folder to find "index.tex". If all else fails, look at the index?.txt
copies on the examples.html web page.
-
Note: I recommend using a simple text editor if you are still learning
LaTeX. A more fancy one like TeXstudio is probably just an additional
big distraction at this point.
-
Microsoft Windows users only: The "Notepad" editor is
convenient to edit index.tex, since every Windows version has it.
Also, you can go to a given line number in it. But be sure in the
menus to deselect word-wrap. (I do not recommend Wordpad, because its
various menu options do not work in LaTeX documents. That would be
very confusing. And no, Microsoft Word will not work at
all.)
-
In the editor window, spend some time reading through all of the
example index.tex. This will give you a good idea what LaTeX is all
about. Do not worry too much about details right now. (Or if you
insist, open the web
page intro_to_latex in a second
browser tab.)
-
Now you want to try to create a pdf document, index.pdf, from
index.tex. Go back to the l2h_menu (terminal) window. When it is
active, press the "l" key. This will process index.tex using latex.
(If you get no response, check the "Caps Lock" key: "L" instead of "l"
will not work.) There should be no errors or major warnings. If an
error or major warning does occur, see the
trouble shooting web page.
-
MiKTeX users only: When latex is run for the first time,
MiKTeX will start fetching the needed packages from the web. At that
time, processing may appear to freeze, especially if your firewall
gets involved. Just give it some time. If things seem to stay frozen
long, make sure that the firewall is not prompting you for permission.
-
Next press the "p" key to make a pdf file, if it has not yet been made
already. Open the created pdf file with the "P" key (or by double
clicking index.pdf in the document_1 folder) and check that everything
is OK. If not, see the
trouble shooting web page.
-
Now you want to try to process index.tex into web pages. Press the
"2" key followed by the "w" key. Respond to the queries, normally by
just hitting "Enter". After the web pages have been made, check them
in your browser by using the "W" key. Or use your browser to open
file "index.html" inside subfolder "web-pages" inside the document_1
folder. If there is a problem, see the
trouble shooting web page.
For those who want to start processing their own already existing
LaTeX document: Proceed with web
page use_your_own now.
For those who write in Greek or a nonWestern European
language: You will want to change to one of the examples 5 or 6
now. Exit your editor, (Notepad, gedit, or whatever), with
index.tex first. Then double click the document_1 folder if it
is not open already, and find and delete the document source
"index.tex". Since your operating system may hide the ".tex" part
from you, and there are many "index" files, you may want to go into
the view menu to enable details. Or right-click the likely candidates
and select "Properties". After you have found and deleted index.tex,
press the "-" (hyphen) key in the l2h menu. L2h will see that
index.tex has disappeared and offer you a choice of a new one. Select
example 5 or 6. Use the "\" key in the l2h menu to re-enter your
editor. Read through the brand-new section on "Internationalization".
Use the "l" key to process the document and see if it still works.
Note that in my experience, XeLaTeX may seem to freeze at some font
initializations, but it comes back. Have a bit of patience while
running "l" the first time. Afterwards, check the new pdf. Press "2"
and "w" again to make web pages and check them. If there is a
problem, see the
trouble shooting web page.
Now go back to the editor window with the example source index.tex.
Make a small change, like changing the author's name into your own.
Save the file. To do so click on "File" in the top left corner and
select "Save". Or there might be a save icon on the toolbar. Or
press Ctrl+s (i.e. press "s" while holding down Ctrl.) Go to the l2h
menu and press "l" again to process the change. Press "p" (if needed)
and "P" to check that the name has indeed been changed. (If the pdf
file is still open in Acrobat Reader, select "Reload" in the "File"
menu to see the changes.)
Make another change. Until you get some experience, make changes one
at a time, saving and pressing the "l" menu key after each one. That
is to prevent you from potentially having to deal with more than one
error at a time. And to make it easier to undo any step that creates
a problem.
If there is an error in processing, try hitting the "h" key for help.
See the intro_to_latex web page for
more information (press the "H" key). Have fun learning LaTeX!
Additional notes:
-
For people to be able to access the document remotely, folder
document_1 will typically have to be placed in some special location,
like inside a "public" or "public_html" folder.
-
If people now load http://YOUR.WEBPAGE.LOC/document_1, (which is
shorthand for http://YOUR.WEBPAGE.LOC/document_1/index.html), in a
web-browser, they will get a format selection page. This page will
allow them to select between the pdf and web page versions of the
document.
-
If you would like to change the format selection page, you can
edit index.html with a text editor if you know the html language, or
if you do not change things you do not understand. You could also use
Microsoft Word or some web page editor. (WordPerfect may not be a
good idea. But it can be used if you remember to export to html.)
After that, l2h may not be able to update the selection page if the
data change, but so what? You now know how to do it yourself.
-
If you would like to get rid of the format selection page
altogether and send people directly to the web pages, do not
move folder "document_1" into "public" or "public_html". Instead put
a copy of its subfolder "web-pages" into "public" or
"public_html". Rename this copied "web-pages" folder into
"document_1". You might also want to put a copy of the pdf file
index.pdf inside it. This pdf can then be accessed by using
http://YOUR.WEBPAGE.LOC/document_1/index.pdf. Note: if you change the
document, you will need to delete the old copy of "web-pages" in
"public" or "public_html" and copy in the new one as before.