|
|
| HowTo Linux Zone | Linux Zone Home | E-Mail Me | LinuxDoc+Emacs+Ispell-HOWTO Author: Philippe MARTIN (feloy@wanadoo.fr)
Translator: Sébastien Blondeel (Sebastien.Blondeel@lifl.fr)
v0.4, 27 February 1998
This document is aimed at writers and translators of Linux HOWTOs or
any other paper for the Linux Documentation Project. It gives them
hints at using tools including Emacs and Ispell.
______________________________________________________________________
Table of Contents
1. Preamble
1.1 Copyright
1.2 Credits
1.3 Comments
1.4 Versions
2. Introduction
2.1 SGML
2.2 The
2.3 (TT
3. Your first document.
3.1 From a text document
4. Configuring
4.1 Accented Characters
4.1.1 The displaying of 8-bit characters
4.1.2 The typing of 8-bit characters
4.1.2.1 The
4.1.2.2 The
4.1.3 The displaying of 8-bit SGML characters
4.2 SGML mode
4.3 PSGML mode
4.4 Miscellaneous
4.4.1 auto-fill mode
5. Ispell
5.1 Choosing your default dictionaries
5.2 Selecting special dictionaries for certain files
5.3 Spell-checking your document
5.4 Personal dictionary versus local file dictionary
5.5 Typing spell-checking
6. Dirty Tricks
6.1 Inserting a header automatically
6.1.1 by inserting a file
6.1.2 by running a routine
7. An
______________________________________________________________________
1.
Preamble
1.1.
Copyright
Copyright Philippe Martin 1998
You may redistribute and/or modify this document as long as you comply
with the terms of the GNU General Public Licence, version 2 or later.
1.2.
Credits
Special thanks go to Sébastien Blondeel, who is a nasty bugger and
asked me so much about Emacs setup. His clever questions have allowed
me to understand it better and pass the knowledge to you through this
document.
1.3.
Comments
Do not hesitate to tell me any thing you think will help make this
document better. I will examine your critics thoroughly.
Do not hesitate as well to ask me any questions related to topics
discussed here. I will be more than happy to answer them, as they may
help me further improve this document. (-- Translator note: If the
English is ugly, well then that goes to me!--)
1.4.
Versions
This paper is about the following versions:
· Sgml-tools version 0.99,
· Emacs version 19.34,
· Ispell version 3.1,
· All Emacs libraries referred to in this document are distributed
with the above Emacs version, apart from iso-sgml, which is
distributed with XEmacs, and psgml, which is a stand-alone library.
2.
Introduction
2.1.
SGML
Standard Generalised Mark-up Language, or SGML, is a language to
define document types.
For instance, one may define the document type recipe, with a first
part presenting the ingredients, a second part introducing the
accessories, a third part giving step by step instructions for baking
the cake, and a nice final picture to show the outcome of it all.
This is called a Document Type Definition. It does not define what
the final product will look like, it only defines what it may contain.
To use the same example again, I'm sure that upon reading my idea of a
recipe, you recognised yours, or your favourite cook's. Nevertheless,
they actually look different: mine have a picture in the upper left
corner of the bathroom cupboard, and the ingredients list can be found
in the back garden, between the swimming pool and the barbecue. Yours?
Thanks to this standard definition, one can write a document, without
taking into account what it will look like in the end to the reader.
2.2.
The LinuxDoc Type Definition
This type is used to write, as you might have guessed, documents
related to Linux.
Such documents are generally built as follows: they start with a title
followed by the name of the author, and the version number and date.
Then comes the abstract (so you don't have to browse through it before
realizing it isn't what you were looking for after all), then the
contents which show the structure so that those in a rush can go
directly to the part they want to read.
Then comes a list of chapters, sections, paragraphs. Among these, one
can insert bits of programs, change the font to emphasise a word or a
sentence, insert lists, refer to another part of the document, etc.
To write such a document, you just need to specify at the right time
the title, the author, the date, and the document version, the
chapters and sections, say when a list is to be inserted, what its
elements are etc.
2.3.
SGML-Tools
SGML-Tools will turn the specification of a document into the final
result in the form you prefer. If you want it in your personal
library, you will choose PostScript. If you want to share it with the
world through the Web, it will be HTML. If you can't help it and must
read it under Windows, you can turn it into RTF to be able to read it
with any word processor. Or maybe use all three formats to accommodate
your changing moods.
SGML-Tools are available via anonymous FTP at
ftp://ftp.lip6.fr/pub/sgml-tools/
3.
Your first document.
3.1.
From a text document
If you want to turn a text document into SGML to port it to other
formats, this is the way to go:
1. Add the following lines at the very beginning:
<!doctype linuxdoc system>
<article>
<title>Title Goes Here</title>
<author>
name of author, author's e-mail, etc.
</author>
<date>
version and date
</date>
2. If you describe briefly the contents of the document in the
beginning, surround that paragraph with the <abstract> and
</abstract> tags.
3. Then insert the <toc> tag, which stands for Table Of Contents.
4. At the beginning of each new chapter, replace the line giving the
number and title of the chapter with:
<sect>The Title Of The Chapter
and add the </sect> tag at the end of the chapter.
Note : You don't have to put the chapter number, this is done
automatically.
5. Proceed in the same way for sections. You need to delete their
numbers and tag their titles with <sect1> and they end with
</sect1>.
6. You can also define as many as 4 levels of nesting in the sections,
using <sectn> and </sectn> where n= 2, 3, or 4 in a similar way.
7. In the beginning of each paragraph, insert the <p> tag.
8. If you need to emphasise some parts, tag them with <it> and </it>
(italics), <bf> and </bf> (bold face), or <tt> and </tt>
(typewriter style).
9. To insert a list like the following one:
This is a four lines list:
- first line goes here
- second line comes next
- yet another one
- that's it.
you must replace it with:
This is a four lines list:
<itemize>
<item>first line goes here
<item>second line come next
<item>yet another one
<item>that's it.
</itemize>
10.
When a whole block is a part of a program, or something else that
needs to stick out:
<verb>
10 REM Oh my God what's this?
20 REM I thought this had long disappeared!
30 PRINT "I am back to";
40 PRINT "save the world."
50 INPUT "From whom, do you reckon? ",M$
60 IF M$="Bill" THEN PRINT "Thou art wise.":GOTO PARADISE
70 ELSE PRINT "You ain't got a clue...":GOTO RICHMOND
</verb>
11.
Thus far, your SGML formating skills are fairly decent. If you want
to refine your document, you may have a look at the user's guide
for SGML-Tools, which gives more details about the LinuxDoc
document type.
4.
Configuring Emacs
4.1.
Accented Characters
If you want to write documents in French or in any other western
European language, you will need 8-bit characters. This is how to set
Emacs up to tell it to accept such characters.
4.1.1.
The displaying of 8-bit characters
To let Emacs display 8-bit characters, you will need the following
lines in your .emacs file:
(standard-display-european 1)
(load-library "iso-syntax")
If you are using Emacs on a terminal which has no 8-bit support, you
can use the iso-ascii library ((load-library "iso-ascii")), which
tells Emacs to display such characters to its best approximation.
4.1.2.
The typing of 8-bit characters
If your keyboard allows you to enter accented characters, no problem.
If not here are some remedies:
4.1.2.1.
The iso-acc library
The Emacs iso-acc library will let you type 8-bit characters from a
7-bit keyboard.
To use it, insert the following in your .emacs file:
(load-library "iso-acc")
Then, upon running Emacs and opening the file you need to edit, type
Meta-x iso-accents-mode.
You can then enter the é of the French word café typing ' then e. More
generally, you will type an accented character typing the accent
first, then the letter to accent (upper or lower case). The following
are the accents you may use:
` : Grave
^ : Circumflex
" : Dieresis
~ : Tilde, cedilla, and other particular cases (cf iso-acc.el).
/ : To bar a letter, etc.
If you need one of these characters and not an accented letter, type a
space next to it. For instance, to type l'éléphant, type l ' <spc> ' e
l ' e ...
You will find all the possible combinations in the iso-acc.el file.
4.1.2.2.
The<Meta> key
Some terminals will let you type 8-bit characters with the <Meta> (or
<Alt>) key. For example, pressing <Meta>-i will get you the é
character.
But Emacs reserved the <Meta> key for other uses, and I know of no
library which lets you use it for accented characters.
This is a solution:
(global-set-key "\ei" '(lambda () (interactive) (insert ?\351)))
_ ___
Such a line, if inserted in your .emacs file, will let you type é
using the <Meta>-i keystroke. You can redefine in such a way the
combinations you need if you replace i with the right key and 351 with
the right code (the code being taken from the ISO-8859-1 character
set).
Warning! Some local modes may redefine such key combinations.
4.1.3. The displaying of 8-bit SGML characters
Under SGML, you can type accented characters with macros. For example,
the é key is é. Generally, the applications that need to read
SGML can read 8-bit characters and there is no need to use these
macros. But some may not be able to do so. Given that there is a way
to solve this problem, it would be a waste to let these crash.
The iso-sgml library will let you type accented characters under
Emacs, like always, but upon saving your file to the disk, it will
turn these 8-bit characters into their SGML equivalent.
It is therefore easy, thanks to this library, to type and reread your
document under Emacs, and you can be sure a non 8-bit clean
application will accept you document.
To use this library, you just need to add the following lines to your
.emacs file:
(setq sgml-mode-hook
'(lambda () "Defaults for SGML mode."
(load-library "iso-sgml")))
4.2.
SGML mode
Upon loading a file with the .sgml extension, Emacs enters the sgml
mode automatically. If it doesn't, you can tell it to do so manually
by typing Meta-x sgml-mode, or automatically by adding the following
lines to your .emacs file:
(setq auto-mode-alist
(append '(("\.sgml$" . sgml-mode))
auto-mode-alist))
This mode will let you choose how to insert 8-bit characters for
example. With Meta-x sgml-name-8bit-mode (or the menu item SGML/Toggle
8-bit insertion), you can choose to type 8-bit characters as is, or in
SGML form, i.e. in the form &...;.
It will as well let you hide or show SGML tags, with Meta-x sgml-tags-
invisible (or the menu item SGML/Toggle Tag Visibility).
4.3.
PSGML mode
PSGML mode helps a lot to edit SGML documents with Emacs.
The psgml-linuxdoc documentation explains how to install this mode and
use it with LinuxDoc.
4.4.
Miscellaneous
4.4.1.
auto-fill mode
In the normal mode, when you type a paragraph and get to the end of
the line, you must use the <Return> key yourself to get to the next
line, or else your line goes on through the whole paragraph. When you
use <Return> to get to the next line, you get a paragraph with ragged
right margins.
If you let some lines go beyond a reasonable width, you won't be able
to see them with some editors.
The auto-fill mode automates this boring task: when you go further
than a certain column (the 70th by default), you are automatically
taken to the next line.
This is how to use this mode, and set the width of your lines to 80:
(setq sgml-mode-hook
'(lambda () "Defaults for SGML mode."
(auto-fill-mode)
(setq fill-column 80)))
5.
Ispell
If you want to spell-check your document from within Emacs, you may
use the Ispell package and its Emacs mode.
5.1.
Choosing your default dictionaries
You can set up Emacs so that upon loading a file, it chooses
automatically which dictionaries to use (you can use several). The
first one, certainly the most important, is the main dictionary,
distributed with Ispell. You can choose among several languages. The
second one is your personal dictionary, where Ispell will insert words
it couldn't find in the main dictionary but you told it to remember.
If you wish to use as a default dictionary the French dictionary that
comes with Ispell, and if you wish to use the file .ispell-dico-perso
in your home directory as a personal dictionary, insert the following
lines in your .emacs file:
(setq sgml-mode-hook
'(lambda () "Defauts for SGML mode."
(setq ispell-personal-dictionary "~/.ispell-dico-perso")
(ispell-change-dictionary "francais")
))
5.2. Selecting special dictionaries for certain files
You may have a little problem if you do not spell-check documents in
the same language at all times. If you translate documents, it is very
likely that you swap languages (and dictionaries) very often.
I don't know of any Lisp way of selecting, either automatically, or
with a single mouse click, the main and personal dictionaries
associated to the language currently being used. (If you do, please
tell me!)
However, it is possible to indicate, at the end of the file, which
dictionaries you want to use for the current file (and only this one).
It suffices to add them as commentaries, so that Ispell can read them
upon launching a spell-check:
<!-- Local IspellDict: english -->
<!-- Local IspellPersDict: ~/emacs/.ispell-english -->
If you have previously defined, in your .emacs file, that your default
dictionaries are the French dictionaries, then you can add these lines
in the end of any file written in English.
5.3.
Spell-checking your document
To spell-check the whole of your document, use, from anywhere in the
document the Meta-x ispell-buffer command. You may as well only run
the checking on a region in your document:
· Mark the beginning of the region with Ctrl-Spc (mark-set-command),
· Go to the end of the region to check,
· type Meta-x ispell-region.
Emacs then runs Ispell. Upon meeting an unknown word, this one shows
you said word (usually highlighted) and prompts you for a key:
· spc accepts the word, this time only,
· i accepts the word and inserts it in your personal dictionary,
· a accepts the word for this session,
· A accepts the word for this file, and inserts it in the local file
dictionary
· r allows you to correct the word by hand
· R allows you to correct all the occurrences of the misspelled word,
· x stops the checking, and puts the cursor back in place,
· X stops the checking and leaves the cursor where it is, letting you
correct your file; you will be able to continue the spell-checking
later if you type Meta-x ispell-continue,
· ? gives you online help.
If ispell finds one or several words close to the unknown one, it will
show them in a little window, each one of them preceded by a digit.
Just type this digit to replace the misspelled word with the
corresponding word.
5.4.
Personal dictionary versus local file dictionary
The i key will let you insert a word in your personal dictionary,
whereas A will let you insert a word in the local file dictionary.
The local file dictionary is a sequence of words inserted at the end
of the file, as comments, reread by Ispell each time it is run on the
file. This way, you can accept some words, acceptable in this file,
but not necessarily acceptable in other files.
As far as I am concerned, I think it is better that the personal
dictionary be reserved for words the main dictionary doesn't know but
which belong to the language (like hyphenated words), plus some common
words like proper nouns or others (like Linux), if they don't look too
much like a real word of the main dictionary; adding too many words in
the personal dictionary, such as first names, may be dangerous,
because they may look like a word of the language (one can imagine
Ispell being mystified on the following: `When the going gets tof, the
tof get going (-- Tof is a French abbreviation for the first name
Christophe.--)
5.5.
Typing spell-checking
Ispell can spell-check your file while you're typing. You need to use
ispell-minor-mode for this. To start it or stop it, type Meta-x
ispell-minor-mode. Ispell will beep you each time you type a word it
doesn't know.
If those beeps hassle you (or your roommate is taking a nap), you can
replace those annoying beeps with a flash on the screen, with the
command Meta-x set-variable RET visible-bell RET t RET. You can add
the following line in your .emacs and silence Emacs forever:
(setq visible-bell t)
6.
Dirty Tricks
6.1.
Inserting a header automatically
Emacs allows you to hook some actions to any event (opening of a file,
saving, running a new mode, etc).
The autoinsert library uses this feature: when you open a new file
under Emacs, this library inserts, according to the type of the file,
a standard header.
In our case, this standard header could well be the part declaring the
document type (LinuxDoc), the title, the author, and the date.
I will describe here two ways to insert such a header. You could
insert a template file containing the information to insert, or you
could run an elisp routine.
6.1.1.
by inserting a file
You must first tell Emacs to run the auto-insert when opening a file,
then to read the autoinsert library which declares the auto-insert-
alist list which we need to change. This list defines the header to
insert for each file type. By default, the file to insert must be in
the ~/insert/ directory, but it is possible to redefine the auto-
insert-directory variable if you want to put it somewhere else.
Add the following lines to your .emacs file to insert the
~/emacs/sgml-insert.sgml file each time you open a new SGML file:
(add-hook 'find-file-hooks 'auto-insert)
(load-library "autoinsert")
(setq auto-insert-directory "~/emacs/")
(setq auto-insert-alist
(append '((sgml-mode . "sgml-insert.sgml"))
auto-insert-alist))
You can then write in the ~/emacs/sgml-insert.sgml file your
customised header, then re-run Emacs and open some foobar.sgml file.
Emacs should ask you to confirm the automatic insertion, and if you
answer yes, insert your header.
6.1.2.
by running a routine
This works like before, but instead of setting the auto-insert-alist
to a file to insert, you need to set it to a function to execute. This
is how to proceed, taking for granted you want to write this function
in a file named ~/emacs/sgml-header.el. (there's no need to burden
your .emacs file with such a function, as it may turn out to be quite
long):
(add-hook 'find-file-hooks 'auto-insert)
(load-library "autoinsert")
(add-to-list 'load-path "~/emacs")
(load-library "sgml-header")
(setq auto-insert-alist
(append '(((sgml-mode . "SGML Mode") . insert-sgml-header))
auto-insert-alist))
You will find in ``appendix'' an example of insert-sgml-header
function.
G.
An insert-sgml-header function
This function will let the user insert a customised header for a Linux
Documentation Project document in a file. It can be called
automatically when one opens a new file, or explicitly, by the user.
This function prompts the user, through the mini-buffer, for some
pieces of information, some of which are necessary, some of which are
not.
First comes the title. If none is given, the function returns
immediately, and inserts nothing. Then comes the date, the author, his
e-mail and home page (these last two are optional).
Then comes a request for the name of the translator. If there is none,
just type Return, and no further prompting about a hypothetical
translator will be done. If there is one, you are asked for his e-mail
and home page (optional as well).
This function then prints your request to the current buffer,
including of course all the information you typed in a set up form,
and including as well the tags which will serve for the abstract and
the first chapter. It finally puts the cursor in the place where the
abstract needs to be typed.
(defun insert-sgml-header ()
"Inserts the header for a LinuxDoc document"
(interactive)
(let (title author email home translator email-translator home-translator date
starting-point)
(setq title (read-from-minibuffer "Title: "))
(if (> (length title) 0)
(progn
(setq date (read-from-minibuffer "Date: ")
author (read-from-minibuffer "Author: ")
email (read-from-minibuffer "Author e-mail: ")
home (read-from-minibuffer "Author home page: http://")
translator (read-from-minibuffer "Translator: "))
(insert "<!doctype linuxdoc system>\n<article>\n<title>")
(insert title)
(insert "</title>\n<author>\nAuthor: ") (insert author) (insert "<newline>\n")
(if (> (length email) 0)
(progn
(insert "<htmlurl url=\"mailto:")
(insert email) (insert "\" name=\"") (insert email)
(insert "\"><newline>\n")))
(if (> (length home) 0)
(progn
(insert "<htmlurl url=\"http://")
(insert home) (insert "\" name=\"") (insert home)
(insert "\">\n<newline>")))
(if (> (length translator) 0)
(progn
(setq email-translator (read-from-minibuffer "Translator e-mail: ")
home-translator (read-from-minibuffer "Translator home page: http://"))
(insert "Translator : ")
(insert translator)
(insert "<newline>\n")
(if (> (length email-translator) 0)
(progn
(insert "<htmlurl url=\"mailto:")
(insert email-translator) (insert "\" name=\"")
(insert email-translator)
(insert "\"><newline>\n")))
(if (> (length home-translator) 0)
(progn
(insert "<htmlurl url=\"http://")
(insert home-translator) (insert "\" name=\"")
(insert home-translator)
(insert "\"><newline>\n")))))
(insert "</author>\n<date>\n")
(insert date)
(insert "\n</date>\n\n<abstract>\n")
(setq point-beginning (point))
(insert "\n</abstract>\n<toc>\n\n<sect>\n<p>\n\n\n</sect>\n\n</article>\n")
(goto-char point-beginning)
))))
| HowTo Linux Zone | Linux Zone Home | E-Mail Me | Copyright 1999 Linux Zone
