home *** CD-ROM | disk | FTP | other *** search
- 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)
- ))))
-
-
-
-
-
-
-
-