PC World 1999 August

home *** CD-ROM | disk | FTP | other *** search

/ PC World 1999 August / PCWorld_1999-08_cd.bin / doc / HOWTO / LinuxDoc+Emacs+Ispell-HOWTO < prev next >

Wrap

Text File | 1998-05-08 | 25KB | 859 lines

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:   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) ))))