Keywords: manued-e

# Manued Reference Manual

Hitoshi Yamauchi

### Abstract:

Manued is a proofreading method of manuscripts, proposed by Ikuo Takeuchi in No.39 Programming symposium, 1998. Although, Manued is a media independent proofreading method, it is especially effective for exchanging electronic text via E-mail. `manued.el` is an emacs lisp implementation to realize this method on emacs.

## Contents

- Introduction
  - Brief description of Manued
  - Information of this document
- Quick Start of Manued
  - About Manued
  - Installation
  - Starting Manued
- What is Manued?
  - Outline of Manued
  - Examples of Manued document.
- Syntax of Manued
  - Manued command and Manued definition commands of correction symbols
  - Definition commands of correction symbols for manued.el ver.0.9
  - manued commands for manued.el version 0.9 or later
  - Pretty print (after ver.0.9.5)
  - Examples of manued documents
- A Supporting tool manued.el for Manued.
  - Download
  - Short history of manued.el
  - Installation
  - How to use manued.el
  - Customizing manued-minor-mode
  - Customizable variables
  - Bugs
  - Copying
- Manued Tips
  - TeX and Manued
- Manued Links
  - Other implementation of manued.el (By Prof. WADA)
  - Other implementations
  - Manueder (By Suzuki)
- Acknowledgements
- Bibliography
- Index

# Introduction

## Brief description of Manued

Oddly, even in this digital world, revising electric manuscripts is not easy as revising them on a piece of paper with red ink. Especially, in an email environment, it is hard to revise a manuscript since the kinds of usable characters are limited, or your email client might automatically change the text arrangement. However, many people want to exchange manuscripts by email. Conventionally, many people may use a method for revising an electric manuscript like below.

        The Three Laws of Robotics by Azimuth.
                                      ^^^^^^^
                 This may be a mistake for Asimov. And the number of
                 laws was changed from three to four, wasn't it?

        1. A robot may not injure a robot, nor through inaction
                                    ^^^^^ This must be "human being"

           allow a human being to come to harm.

This conventional method indicated correcting position with a symbol `' and proofreading plans with a text. This method always needs much input work and includes some kind of ambiguous, because the proofreading plans are directed by natural language. The main problem of this conventional method comes from this ambiguity. Even if the manuscript has already been digial data, this ambiguity makes automatic extraction of the revised document difficult. Furthermore, information of correcting position with `' sometimes may not be kept depends on the mail client. For example, someone reads a manuscript with proportional font and the other doesn't. In other words, there is the case that it is difficult to specify a correcting point since each person has own environment to read an email including a manuscript.

Manued method solves these problems. The input for designation of proofreading is easy, and it can define exact designation of the correcting region and how to change the text. Therefore, there is no failure the correcting position. There is no mis-recognition of the proofreading text that is a comment or a substitution. In particular, the manued method is independence from the reading environment. We should only assume the manuscript is written as a text file.

Manued has two main notation of proofreading rule. One is ``delete and insert'' rule. This is shown with notation of [original text (delete) /revised text (insert) ; comments ]. Therefore, above text will be changed as follows.

> The Three Laws of Robotics by `[`Azimuth/Asimov; This may be a mistake with Asimov. And the number of laws was changed from three to four, isn't it?`]`. 1. A robot may not injure a `[`robot/human being`]`, nor through inaction allow a human being to come to harm.

Of course, we can use this method with a piece of paper and a pen. However, we assume only an editor program edits the text file. I implemented ``manued-minor-mode'' on the Emacs editor to make this method more useful. In manued-minor-mode, we can use following functions.

- Extracting the original document or the revised one from one manued document automatically
- Searching the proofreading position
- Assistance for inserting manued commands

Since manued method doesn't care the writing environment, an input assisting tools can be implemented on other editors. Just only because I always use the emacs, I implemented the tool on there. So, please let me know if you implemented an assistance tool for manued method on other environment. Examples of demanded environments are as follows.

- vi
- Microsoft Word
- Filter commands for extracting revised document, etc.

## Information of this document

- Copyright (C) 1997-2012 Hitoshi Yamauchi

# Quick Start of Manued

## About Manued

Manued is a method for proofreading of manuscripts, proposed by Ikuo Takeuchi in No.39 Programming symposium, Japan, 1998. The aim of this method is to achieve easy proofreading when people exchange a manuscript via email. I present `manued.el` as one of the implementations to assist the method.

## Installation

`manued.el` depends on the Emacs version 20.7 or later. Installation procedure of `manued.el` is as following.

1. Put the `manued.el` file on your emacs `load-path'.
2. Add the next line to your .emacs file.

       (autoload 'manued-minor-mode "manued" "manuscript editing mode" t)

## Starting Manued

To try out the `manued.el`, you can read the tutorial file(`manued.tut`) or directly enter to the `manued-minor-mode`.

- Read the tutorial
  You can find the `manued-e.tut` file in the manued package. Please read the `manued-e.tut` file in your emacs buffer.
- Directly enter to the `manued-minor-mode`
  1. To enter `manued-minor-mode`, type ``M-x manued-minor-mode''.
  2. Type some texts in the buffer.
  3. To insert a manued swap command, put a mark and type M-x manued-insert-swap-command (or type C-c C-m C-s).
  4. To extract the revised document in another buffer, Type manued-show-newer-in-manued-buffer.
  5. Others: select from a menu item. Type M-n or M-p, this is the search command for manued command.

# What is Manued?

## Outline of Manued

Manued is a proofreading method of manuscripts, proposed by Ikuo Takeuchi in No.39 Programming symposium [3], 1998. Manued stands for MANUscript EDiting Language (and there is another origin. Takeuchi is interested in `Nue'. This is an imaginary creature of Japan. Ma-nue-dou has special meaning in Japanese). The aim of this method is to achieve easy proofreading with exchanging a manuscript via email.(Here is original text in Japanese on the Web.)

When we revise a manuscript sent by email, there are some problems as following.

- We cannot use the special symbols like hand written characters for the proofreading a manuscript. The email usable-character-set is limited.

- Using colors are cumbersome.

- Some mail reader doesn't keep two dimensional information of the document. When the author and the editor use different editor, there is no guarantee that the positioning information of the document is the same. Originally email protocol (RFC 822) does not have any rules about character width, fonts and how to display breaking lines. Therefore, these situations can usually occur.

- We don't want to depend on the line feed position. To send exact correction information, we would like to avoid the effect of the editor software's line feed processing algorithm for a long line, which depends on each editor program.

To solve these problems, we used to exchanging printed paper including proofreading information with red ink via snail-mail. However, this method takes too long in this digital era. Using facsimile is another solution since it has acceptable transmission speed, but receiver must inputs corrections by reading pieces of paper with his/her eyes. So, some errors will be mixed to a manuscript by human error, and input costs for human being is high. There is the OCR technology for recognizing hand written characters, but why we need to use them if we have already typed in the email. In the end, it seems not a good idea to change the media of the manuscript from electric stuffs to printed papers.

[3] pointed out that proofreading for an electric text should have the following features.

- Both revised document and original one are extracted automatically. (required)
- High readability for human being.
- Correction points should be easily found.
- We can put some comments for revised region.
- It should be easy to put revision information to a manuscript.
- Repeated correction directive should be abstracted.

Manued is proposed to satisfy these features and this stands for MANUscript EDiting language. The author presents an implementation to support proofreading with this language.

## Examples of Manued document.

Let me show you some simple examples.

- He was killed at programming.
- When ``Norwegian woods '' is translated to Japanese, it is always interpretented as ``a forest in Norway''. However, 1 of my friends says that the light meaning is a furniture made in Norway. Please tell me which is right?
- Why do people say ``chapter first''?

I emphasized the point which I would like to correct in this text. However, some browsers may not express them. I want to correct above text as follows.

- He was skilled at programming.
- When ``Norwegian wood'' is translated to Japanese, it is always interpreted as ``a forest in Norway''. However, one of my friend says that the right meaning is a furniture made in Norway. Please tell me which is right?
- Why do people say ``chapter one''?

By the conventional method, we correct the text as the following.

    He was killed at programming.
           ^ skilled. This small missing "s" is fatal!

    When ``Norwegian woods'' is translated to Japanese, it is always
                         ^ delete s. I love the Beatles.

    interpretented as ``a forest in Norway''. However, 1 of my friends
    ^ interpreted.                                     ^ Of course one is one,
                                                         but write `one'.

    says that the light meaning is a furniture made in Norway.
                  ^ right.

    Please tell me which is right?

    Why do people say ``chapter first''?
                                ^ one. (I have also same question but
                                        one is right.)

To display this conventional descriptions for browsers, I use special tags to preserve two dimensional information like verbatim (for LaTeX) or pre (for html). However, in email environment (RFC 822), there is no such special directives and this conventional descriptions using `' symbol may corrupted. For example, the same information will be shown in the next paragraph without the tags which preserves two dimensional information. The representation of above text will be varied with each environment, since usual browser ignores successive white spaces and line feeds. Some people can understand next documents, but the others see meaningless texts. It will be clear at a glance that this is not beneficial for the people who can not read the following text.

He was killed at programming. skilled. This small missing "s" is fatal!

When ``Norwegian woods'' is translated to Japanese, it is always delete s. I love the Beatles.

interpretented as ``a forest in Norway''. However, 1 of my friends înterpreted. Ôf course one is one, but write `one'.

says that the light meaning is a furniture made in Norway. right.

Please tell me which is right?

Why do people say ``chapter first''? ône. (I have also same question but one is right.)

In addition, even if an environment can preserve the two dimensional information, it is hard to distinguish among correction information, only the comment and original text. Moreover, first you corrected the latter part of your manuscript and second you correct former part of the manuscript, latter corrected parts are sometimes shifted. In such situation, you must maintain the manuscript for keeping consistency of two dimensional information of revised position. This is not easy. I stressed also that cut and paste manipulation may be harmful for the conventional method. Proofreading with Manued is independent from two dimensional information and can resolve the problems of conventional method using '' symbols.

In Manued method, there are only two replacement rules shown as the following.

- `[A/B]` : This means `delete A and insert B'. The variations are
  1. `[A/]` : Delete A (delete A and insert nothing).
  2. `[/A]` : Insert A (delete nothing and insert A).
- `[A|B|C]` : Swap A with C, so result will be `CBA'.
  The variation is
  1. `[A||C]` : Swap A with C.

According to above rules, the example texts will be presented as the following.

- He was [/s; This small missing "s" is fatal!]killed at programming.
- When ``Norwegian wood [s/; I love the Beatles.'' is translated to Japanese, it is always [interpretented/interpreted] as ``a forest in Norway''. However, [1/one; Of course one is one, but write `one'.] of my friends says that the [light/right] meaning is a furniture made in Norway. Please tell me which is right?
- Why do people say ``chapter [first/one; I have also same question but one is right.]''?

You can see the method is stronger than the conventional method. I think you see how manued works. If there is a tool which processes these rules, manued method will be more powerful and useful. Therefore, I implemented `manued.el`, this program supports manued method. `manued.el` has the following functions : highlighting correction regions, searching manued directives, inserting manued directives, extracting revised document from the original one.

# Syntax of Manued

## Manued command and Manued definition commands of correction symbols

In Manued, there are ``definition commands of correction symbols'' and ``manued commands''. ``Definition commands of correction symbols'' are to avoid dependences of different environments and ``manued commands'' is to indicate proofreading points. We also call definition commands of correction symbols as def-command, because these commands are always started with a string `def'. Def-commands define proofreading symbols in a manuscript. To correspond to next circumstances, def-commands is defined by Manued.

- Since usable characters are limited in email environment, the characters indicating correction points with Manued will be varied according to a document.

- It is almost same with above. If fixed correction characters are used for indicating proofreading point by manued, some environment forces to use too many escape commands. This will degrade readability of the manued document. We would like to avoid these situations using def-commands.

Def-command is always put at the beginning of the document and must be put at the beginning of line. When it is not put at the beginning of line, Manued could not recognize them in my implementation. The names of definition commands of correction symbols are `def' plus each manued command name. For example, `delete and insert' command is defined by `defdelete' def-command.

When you want to set delete command symbol as `*', you should insert next line in your document.

            defdelete *

Then correction region will be written as next.

            [original text*revised text]

This means delete `original text' and insert `revised text'.

When your document has no def-command, default characters are used that suggested in [3] by Ikuo Takeuchi. I will also show the default def-commands in the following section.

##
Definition commands of correction symbols for `manued.el` ver.0.9

This section explains the def-commands.

Def-commands always appears in a proofreaded document as the following.

            defparentheses  [ ]
            defdelete       /
            defswap         |
            defcomment      ;
            defescape
            deforder        newer-last
            defversion      0.9.5

The details of the each line are:

- defparentheses
  Defines the start string and end string of manued command. (default value ``[ ]`')
- defdelete
  Defines delete and insert string. In default, delete the former part of this symbol and insert the latter part of this symbol. For example, `[A/B]` means delete A and insert B. You can exchange the delete part and insert part, see also deforder. (default value ``/`')
- defswap
  Defines swap command. For example, `[A|B|C]` means A and C will be swapped and results is CBA. (default value ``|`')
- defescape
  Defines manued escape command. For example, [This is `~`[foo`~`]/These are `~`[bars`~`]] has delete ``This is [foo]'' and insert ``These are [bars]''. However, too many escapes and is too complicated to read. To avoid this many escape situation, you can re-define manued command strings by using defparentheses. For example, write ``defparentheses { }'', we can rewrite below to {This is [foo]/These are [bars]}. (default value ``~`')
  Here, you must pay attention that escaped symbol is starting manued command strings only when it is not in manued command. This is avoid complicated situation like below.

              The ratio $a_n/b_n$ must be considered here.
              ~[\lim_{n \to \infty} \frac{a_n}{b_n} \]

  If any manued command symbol is processed at any place, all manued command in original text must be escaped. In the above example, '/' of and ] is corresponding to manued command symbol. But these symbols are not in the manued command. It is too cumbersome to escape all the manued command in the text. Therefore, `starting manued region strings' is the only escape target (in here, `[') in the plain text in my implementation.
- defcomment
  Defines comment of manued command. Latter part of this symbol in manued command will be ignored. (default value ``;`')
- deforder
  This defines newer part of delete command. In defdelete command of the manued method, the deleted part is called as the `older' part, and the inserted part is called as the `newer' part. The list in delete command is ordered as [first/last]. You can decide which is delete part. So, these (newer older) and (first last) combinations will be next 4 types.
  - newer-first
  - newer-last
  - older-first
  - older-last
  This deforder of definition commands of correction symbols is only define attribute of delete command, and doesn't define any manued command symbol. (default value ``newer-last`')
- defversion
  Shows the version information for `manued.el`. This is useful information for the `manued.el` program. (default value `(manued-version-num)')

Definition commands should be located at the top of a manuscript and each def-command must be located at the beginning of line. If a manuscript does not include these def-commands, the default manued symbols will be used. `manued.el` checks consistency of def-commands and warns to the user when it is not consistent, for example, if defparentheses has only one argument, it will be warned.

## manued commands for `manued.el` version 0.9 or later

This section explains manued commands with default manued symbols.

- `[A/B]`
  Delete A, insert B The variations are
  1. `[A/]` : Delete A. (delete A, insert null string.)
  2. `[/A]` : Insert A. (delete null string, insert A.)

- `[A|B|C]`
  Swap A with C. This will be CBA.
  The variation is
  1. `[A||C]` : Swap A with C. This will be CA.

- `[; comment ]`
  Set a comment range from `;' to `]'.

- Note
  Sometimes you might want to write the manued command string itself. In that case, you can just escape the command. For example, `~[` will be `[`.

Nesting of these commands is possible, and process is done from the inside to outside. However, non interpretable list of manued command is an error. For example, it is an error that there is no matching defparenthesis (e.g., not closing or closing without opening), or it is also an error like `[A|B/C]` manued sequence.

## Pretty print (after ver.0.9.5)

When you extract the new document with manued, do you want to modify the extracted part? For example, when you use a markup language and you want to emphasize the proofreading part with the language. If yes, there is the way to modify the extracted part.

First, you type

      M-x manued-set-pretty-print-on

and, you apply some Extracting document commands. I will describe this with the following example.

Example 1: Extract from `[A/B;C]` to `\colortext{blue}{A}\colortext{red}{B}\colortext{green}{C}`. Namely, when you want to add some colors at revised parts with TeX.

    (setq manued-pretty-print-format-delete-list
      '("\\colortext{blue}{%s}" "\\colortext{red}{%s}" "\\colortext{green}{%s}"))

This should be included in your `.emacs` or `.manued.el`. The elements of this list correspond with each part of delete command like next:

    (setq manued-pretty-print-format-delete-list
      '("First Element Format" "Second Element Format" "Comment Element Format"))

Each string element will be an argument of the format function of the Emacs.

### Examples of pretty print

Ex. 2: In `[A/B;C]`, when you want to output B part with `Large` strings in TeX way and want to delete part A and comment part.

     (setq manued-pretty-print-format-delete-list
       '("" "{\\Large %s}" ""))

Ex. 3: If you want to change the style of manued expression like from `[A/B;C]` to `{A*B@C}`.

    (setq manued-pretty-print-format-delete-list
      '("{%s*" "%s" "@%s}"))

In manued, the comment part is an optional (not needed). Therefore, when there is no comment in manued expression, the comment part format string is not outputted by default. This behavior is controlled by the variable `manued-pretty-print-null-comment-out-p`. Here, we describe only about delete command, but also the way to control swap command with pretty print mode. See 5.6.3 in details.

## Examples of manued documents

### Example 1

Since defparenthesis can indicate any strings without white space, next example is valid.

        defparentheses ^_^[  ]^_^

        Manued^_^[,/]^_^ stands for ``^_^[Tao of manued/Manuscript Editing
        Language; In Japanese, we call this Manuedou and dou means Tao.]^_^''.

- Original version :
  Manued, stands for ``Tao of manued''
- Revised version :
  Manued stands for ``Manuscript Editing Language''.

### Example 2

When you have an environment that can use multi-byte characters, you may use some def-commands with multi-byte characters. This document of Japanese version shows such examples. But this document does not assume such environment, I omit the example multi-byte def-command.

### Example 3

The following text looks like a SGML, HTML, XML.

        defparentheses      <manued>  </manued>
        defdelete   /

        ``Don't worry, Miss Sakuara. The manuscript still is.
          <manued>/At here.</manued>''

        ``Give me the supreme <manued>sing/song.</manued>''

        `` <manued>Reverse/Return</manued> to your original figure.''

- Original version :
  ``Don't worry, Miss Sakuara. The manuscript still is.'' ``Give me the supreme sing'' ``Reverse to your original figure.''
- Revised version :
  ``Don't worry, Miss Sakuara. The manuscript still is. At here.'' ``Give me the supreme song. ``Return to your original figure.''

### Example 4

Tateoka proposed the following definition, this looks like `sed' commands.

        defparenthesis s/ /g
        defdelete //
        defescape

        Manued was proposed by Ikuo Takeuchi who grieved that editing
        manuscripts by s/Electric mail//email; Later, you use the word
        email, please standardize your terms./g was not smoothly done
        because two dimensional information s/od//of/g document is not
        kept in email.

- Original version :
  Manued was proposed by Ikuo Takeuchi who grieved that editing manuscripts by Electric mail was not smoothly done because two dimensional information od document is not kept in email.
- Revised version :
  Manued was proposed by Ikuo Takeuchi who grieved that editing manuscripts by email was not smoothly done because two dimensional information of document is not kept in email.

# A Supporting tool `manued.el` for Manued.

## Download

You can find the latest version and documents in the following Web sites.

- https://github.com/emacsmirror/manued

## Short history of `manued.el`

`manued.el` is an Emacs lisp program for supporting the Manued proofreading method. Manued method itself is a proofreading method for correcting electric texts. You can use it even on a paper. But if I had a program, then I would like to have the following features: emphasizing manued commands (e.g. using colors), extracting the revised text and the original text automatically. `manued.el` offers to add colors to manued commands, to search correction points, to extract the revised text and the original text, and to assist to input manued commands.

I have been interested in Lisp language since I took the Masahiko Sato's class, functional language. At that time, I have not written any Lisp programs. I sometimes tried to write a lisp program, but I always failed because I don't have a killer problem which I really want to solve and I had no friend who is a lisper.

Several years are passed, I must exchange manuscripts to correct with research colleagues via email. It was so cumbersome. I found it was so difficult to revise the manuscript via email, especially just before the deadline of our paper. First, I wrote my manuscript on my computer, then I printed it out, checked it by red pen, then, I inputted correction points back to the computer.

Once I supervised a student. One day he send me his draft of his master thesis. The time of correcting work reaches several hours and the time of input work was taken more hours. I used the conventional method for correcting manuscript. However, there were so much errors and we both frustrated.

Then, I joined the programming symposium and heard the idea of manued. I was immediately fascinated this idea. I thought this is the program I should write and my natural choice is emacs lisp since I am a user of the editor. Professor Takeuchi commented that ``This program should be very easy to implement. I think the fourth grade student entered his/her graduation thesis can be accomplish to write this program.'' I thought this should be a good exercise to start writing lisp program for me. Fortunately, Atusi Maeda, a great lisper helped me a lot.

## Installation

`manued.el` is based on Emacs Version 20.7 or later.

1. Put `manued.el` the directory which is included load-path.
2. Add next line to `.emacs'.

         (autoload 'manued-minor-mode "manued" "manuscript editing mode" t)

## How to use `manued.el`

Open any text by emacs, then type `M-x manued-minor-mode' to enter the manued-minor-mode. The following commands are available. Of course you can customize the key bindings.

- Starting mode and others
  - M-x manued-mode
    This is alias of next manued-minor-mode, see next item.
  - M-x manued-minor-mode
    Enter manued minor mode. `manued.el` after version 0.9.0 has only minor mode. The author usually uses the manued mode with TeX-mode, LaTeX-mode, indented-text-mode and mail draft mode only. Then, for easiness of maintenance for this code, the author abolished manued-major-mode.
  - M-x manued-show-version
    Show the version of `manued.el`.
  - M-x manued-insert-header
    Insert the def-command header for manued command.

- Hi-light
  - M-x manued-hilit-older
    Hi-light and the original part of document in delete command is emphasized.
  - M-x manued-hilit-newer
    Hi-light and the revised part of document in delete command is emphasized.
  - M-x manued-recenter-hilit
    Set current point to the center of the screen and re-hilit the buffer.

- Extracting document
  - M-x manued-show-older-in-manued-buffer
    Extract the original document from current buffer to another buffer.
  - M-x manued-show-newer-in-manued-buffer
    Extract the revised document from current buffer to another buffer.
  - M-x manued-show-older-region
    Extract the original document from a designated region of current buffer. The designated region will be changed.
  - M-x manued-show-newer-region
    Extract the revised document from a designated region of current buffer. The designated region will be changed.
  - M-x manued-eval-last-manuexp
    Extract the revised document from the prior manued command.
  - M-x manued-set-pretty-print-on
    Set pretty print mode on.
  - M-x manued-set-pretty-print-off
    Set pretty print mode off.

- Insert the Manued commands
  - M-x manued-insert-swap-command
    Insert swap command. The `A' part of swap command is filled with designated region. When manued-is-swap-command-with-comment-on is `t', comment symbol is inserted together.

  - M-x manued-insert-swap-command-toggle-comment
    Almost same as manued-insert-swap-command, but condition of comment insertion is reversed. Comment symbol is inserted when manued-is-swap-command-with-comment-on is nil.

  - M-x manued-insert-delete-command
    Insert delete command. The `delete' part of delete command is filled with designated region. When manued-is-delete-command-with-comment-on is `t', comment symbol is inserted together.

  - M-x manued-insert-delete-command-toggle-comment
    Almost same as manued-insert-delete-command, but condition of comment insertion is reversed. Comment symbol is inserted when manued-is-delete-command-with-comment-on is nil.

  - M-x manued-insert-comment-region]
    Insert comment command. The designated region is surrounded with comment command.

  - M-x manued-insert-comment-at-point
    Insert comment command at the current point.

- Search
  - M-x manued-next-l-parenthesis
    Search next manued command from current point.

  - M-x manued-previous-l-parenthesis
    Search previous manued command from current point.

## Customizing `manued-minor-mode`

Manued.el provides two main customizing methods. One of them is to change the emacs lisp variables. I will show the list of customizable variables later. Another method is to use the hook function. The entry function `manued-minor-mode' calls

            (run-hooks 'manued-minor-mode-hook)

after all initialization is done. So, you can customize manued-minor-mode by using this hook function. (However, now I did not use this feature, this is only available.)

One of recommended methods is that you put the file `.manued.el` in your home directory and set variables in the file, then you read the file from `.emacs`. For this, add your `.emacs` file to next line.

            (load-file "~/.manued.el")

## Customizable variables

### Manued definition commands of correction symbols (def-command)

When you set the following variables in `.emacs` file or set by any other method, your definition is valid except when def-commands are appeared in manued document. The default values of def-command is also shown in `()'.

- manued-l-parenthesis-str
  The default value of start symbol of manued command. (default ``[`')
- manued-r-parenthesis-str
  The default value of end symbol of manued command. (default ``]`')
- manued-delete-str
  The default value of delete symbol of manued command. (default ``/`')
- manued-swap-str
  The default value of swap symbol of manued command. (default ``|`')
- manued-comment-str
  The default value of starting comment symbol of manued command. (default ``;`')
- manued-escape-str
  The default value of escape symbol of manued command. (default ``~`')
- manued-order-str
  The default applying order of delete command. (default `older-first') The candidate variables are ``older-first'', ``newer-last'' or ``older-last'', ``newer-first''. The form of delete command of manued is [first/last], you must decide which is the revised part (= newer-part). See the item deforder in section 4.2.

`manued.el` checks that these def-commands have consistency or not. If there is no consistency (e.g. two def-commands has same symbol.), `manued.el` may warn it. Then you should change definition of def-commands.

### hi-light colors

There are three choices for using color. Set following variable to `manued-use-color-hilit`.

- Use the color as possible as it can.(`t`)
- Never use the color.(`nil`)
- Following the font-lock-mode status.(`'follow-font-lock-mode`)

Example.

    (setq manued-use-color-hilit 'follow-font-lock-mode)

A list which has 6 color names are used to specify the hi-lighting colors. Emacs teaches us what color names are available by typing `M-x list-colors-display'. Each elements of the list means as follows.

    '(delete-first-color delete-last-color
      swap-alpha-color swap-beta-color swap-gamma-color
      comment-color command-color)

Where,

- delete-first-color, delete-last-color
  Specify colors of text in delete command as `[`delete-first-color/delete-last-color`]`.
- swap-alpha-color, swap-beta-color, swap-gamma-color
  Specify colors of text in swap command as `[`swap-alpha-color | swap-beta-color | swap-gamma-color`]`
- comment-color
  Specify the text color in comment region.
- command-color
  Specify the manued command symbol color. As default, manued command symbols are ``[`',`/',`;',``]`'.

For example, according to default values, this color list is set with

     '(red gray60 blue red green4 BlueViolet gray60).

The variables of keeping default color list is next.

- manued-first-hilit-color-list
  The color list of when first part is emphasized in delete command.
- manued-last-hilit-color-list
  The color list of when last part is emphasized in delete command.

###
Pretty print

- manued-pretty-print-format-delete-list
  Format list of pretty print for delete command.
  (default `'("\\textnormal{%s}" "\\textbf{%s}" "\\textit{%s}")`)

- manued-pretty-print-format-swap-list
  Format list of pretty print for swap command.
  (default `'("\\textbf{%s}---" "\\textbf{%s}" "---\\textbf{%s}" "(\\textit{%s})")`

- manued-pretty-print-on-p
  If `t`, the document extraction command gives you the output with pretty print style. (default `nil`) This variable can be changed with commands (`M-x manued-set-pretty-print-on`, `M-x manued-set-pretty-print-off`). If you want to get the output as always pretty print style, set this variable to `t`.

- manued-pretty-print-null-comment-out-p
  When A manued expression has no comment, pretty print does not output the comment part format strings. However, if you want to output the comment part format whether a manued expression has or doesn't have a comment, you can set this variable `t`. Notice: this variable is not buffer local.

### Other customization

- manued-mode-syntax-table
  Default value of syntax-table (default : text-mode-syntax-table)
- manued-mode-abbrev-table
  Default value of abbrev-table (default : text-mode-syntax-table)
- manued-mode-map, manued-minor-mode-map
  Default value of keymaps
- manued-is-delete-command-with-comment-on
  When this value is `t', manued-insert-delete-command inserts delete command with comment symbol.
- manued-is-swap-command-with-comment-on
  When this value is `t', manued-insert-swap-command inserts swap command with comment symbol.
- manued-is-auto-insert-header
  This value is a list of `'(auto-insert query-when-insert insert-point)`. This value controls inserting def-command and behavior of inserting when no def-command is found in manued document.
  - `auto-insert` : When this is t”¤and when entering manued-minor-mode, `manued.el` tries to insert def-command header if def-command is not found in manued document.
  - `auto-insert` (This is effective iff `auto-insert` is t.) : When this is t, `manued.el` asks insert or not to user with interactively.
  - `insert-point` (This is effective iff `auto-insert` is t.) : There are three cases according to the value.
    - t : Insert header at current cursor position of the buffer.
    - nil : Insert header at the top of the buffer (point-min).
    - number : Insert header at this number position.
- manued-ask-if-formatted-buffer-is
  When this value is t, and when document extracted buffer is already exist, ask user to overwrite the buffer or not.
- manued-defcommand-head-str-list
  List of string which can add top of def-command. Default values are ``%'' and ``%%'', since you can put def-command into the TeX comments.

## Bugs

- Current version (0.9.5) does not use `font-lock-mode`, so, some environment can not be hi-lighted.

## Copying

`manued.el` (C) Copyright 1998-2012 Hitoshi Yamauchi

This software is free software. There is absolutely no warranty about this program. This software can be redistributed only under GNU copyleft (most recently version of GNU General Public License).

Suggestions, comments and bug reports are welcome to

# Manued Tips

- TeX and Manued (How to compile a TeX file which extracted by show newer command immidiately.)
  - When def-command harms TeX compilation.
  - When TeX option is deleted with manued processing.

## TeX and Manued

How to compile TeX file which is extracted by show-newer-command immediately.

### When def-command harms TeX compilation.

I would like to latex compile the output of show-newer-command immediately. (First, you apply manued-show-newer-in-manued-buffer to the current buffer. Second, you write *manued* buffer which is result of the command to foo.tex file by using M-x write-file. Finally you compile `foo.tex' file.) However the compilation may fail because of manued def-commands. One solution is not to use def-command in the manuscript and to set manued-def-* variables by elisp startup file(.emacs). But one of the meanings of def-command is to keep consistency between the def-command symbols and the manued commands within the document. Therefore, it is not a good idea to eliminate def-command header, especially a manuscript is exchanged via email since this is just the case that such consistency should be kept.

`manued.el` can recognize extended def-command which is attached with some strings at top of def-command. You can set the head strings of def-command to manued-defcommnd-head-str-list. By default, this list includes `%' and `%%' which is the comment symbols of TeX. Next code is recognized by `manued.el` as def-command. However, a manued command must be put at the beginning of line and should not include blank between the head string with the manued command. You can also customize manued-defcommnd-head-str-list to change the header string.

            %%defLparenthesis [
            %%defRparenthesis ]

### When TeX option is deleted with manued processing

Because the default manued command starts at ``[`' and ends with ``]`', this is same as the TeX option argument. I always use Japanese environment, I change the ``[`' and ``]`' to 2bytes parentheses character. However, people use ASCII environment may not use such method. So, one of this solution uses some special strings instead of ``[`' and ``]`'. Next setting is an example.

            (setq manued-l-parenthesis-str ":[:")
            (setq manued-r-parenthesis-str ":]:")

However this seems not so good solution. I actually use a multi-byte characters, but that also depends on your environment.

# Manued Links

## Other implementation of manued.el (By Prof. WADA)

Takeuchi and I introduce another implementation of manued on ``bit'' No. 12, 1999. Prof. Wada also implemented it on emacs.

This section introduces the implementation of manued by Prof. Wada. This implementation focuses to ``see'' the manued document and much smaller than my implementation. This compactness allows to send a manuscript with the code to whom a person did not install `manued.el` and the person can instantly use it.

### Implementation of manued by Prof. Wada.

    ;;
    ;; manued : editing manuscripts for Emacs
    ;; 1998 Eiiti Wada
    ;; manued.el, Copyright (C) 1999 Eiiti Wada”„
    ;;
    ;; (YAMAUCHI, Hitoshi translates the comments to English for explanation.)
    ;;
    ;;[A\B]   means `substitute A with B.'
    ;;[A\]    means `delete A.'
    ;;[\B]    means `insert B.'
    ;;[A|B|C] means `reorder ABC to CBA.'
    ;;[A||B]  means `reorder AB  to BA.'
    ;;[@C]    means comment.
    ;;
    ;; Someone said that it's hard to read the manued document, so I quick
    ;; hacked a tool for easy browsing. Let's try it. This tool works with
    ;; X Window version of Mule editor.
    ;;
    ;; First, put this emacs lisp program in the mule buffer.
    ;; Second, type `esc' `esc', then you will see the prompt `Eval:'
    ;; at the minibuffer, then type (eval-current-buffer) to evaluate whole
    ;; the program.
    ;;
    ;; Next, put the text of your email in the mule buffer, type `esc' `esc'
    ;; and (manued). Then, you can see the colored A, B, C potion in the
    ;; buffer.
    ;;
    ;; If you don't like these colors, type `esc' `esc' again and execute
    ;; (list-faces-display), then you can get the name list of enable
    ;; colors.  According to the color list, change the color definition
    ;; part --- that is in the head part of this program --- to your
    ;; favorite colors.
    ;;

    (make-face 'alpha)
    (set-face-foreground 'alpha "blue")
    (make-face 'beta)
    (set-face-foreground 'beta "red")
    (make-face 'gamma)
    (set-face-foreground 'gamma "green4")
    (setq facealpha 'alpha)
    (setq facebeta  'beta)
    (setq facegamma 'gamma)

    (defun proc-range (beg end)
     (let* (p0 p1 p2 ch)
           (goto-char beg)
           (setq beg (search-forward "[" end t))
           (while beg (proc-sec) (setq beg (search-forward "[" end 0)))))

    (defun proc-sec nil
     (setq p0 (re-search-forward "[]|\[{]" end t))
     (setq ch (string-to-char (buffer-substring (1- p0) p0)))
     (cond ((= ch ?[) (skip) (proc-sec))
           ((= ch ?\\) (findrsb) (alpha beg p0) (beta p0 p2))
           ((= ch ?|) (findvl) (findrsb) (alpha beg p0) (gamma p0 p1) (beta p1 p2))
           ((= ch ?]) (gamma beg p0))
           ((= ch ?{) (skipcb) (proc-sec))))

    (defun skip nil
     (let* (p ch)
           (setq p (re-search-forward "[][{]" end t))
           (while p
                  (setq ch (string-to-char (buffer-substring (1- p) p)))
                  (cond ((= ch ?]) (setq p nil))
                        ((= ch ?[)
                         (skip)
                         (setq p (re-search-forward "[][]" end t)))
                        ((= ch ?{) (skipcb))   ))))
    (defun skipcb nil
     (let* (p ch)
           (setq p (re-search-forward "[}{]" end t))
           (while p
                  (setq ch (string-to-char (buffer-substring (1- p) p)))
                  (cond ((= ch ?}) (setq p nil))
                        ((= ch ?{)
                         (skipcb)
                         (setq p (re-search-forward "[}{]" end t)))))))

    (defun findrsb nil
     (setq p2 (re-search-forward "[][{]" end t))
     (setq ch (string-to-char (buffer-substring (1- p2) p2)))
     (cond ((= ch ?[) (skip) (findrsb))
           ((= ch ?]))
           ((= ch ?{) (skipcb) (findrsb))))

    (defun findvl nil
     (setq p1 (re-search-forward "[|[{]" end t))
     (setq ch (string-to-char (buffer-substring (1- p1) p1)))
     (cond ((= ch ?[) (skip) (findvl))
           ((= ch ?|))
           ((= ch ?{) (skipcb) (findvl))))

    (defun alpha (l r)
     (put-text-property l (1- r) 'face facealpha)
     (proc-range l (1- r)))

    (defun beta  (l r)
     (put-text-property l (1- r) 'face facebeta)
     (proc-range l (1- r)))

    (defun gamma (l r)
     (put-text-property l (1- r) 'face facegamma)
     (proc-range l (1- r)))

    (defun manued nil (proc-range 1 (point-max)))

I thank Prof. Wada Eiiti for permitting to public this code.

## Other implementations

There is an implementation for a text editor named ``Hidemaru'' on Windows 95 and later.

## Manueder (By Suzuki)

Manuediff is a diff program which outputs manued format. Example:

      manuediff file1 file2 > diff.with.manued.format

# Acknowledgements

Thanks to Takeuchi Ikuo to offer ``Manuscript Editing on E-mail'' and its electric text.

I also thanks to Eiiti Wada who gave me an interesting surprise by the concise implementation.

I also should say ``thank you'' to Atusi Maeda who teaches me the lisp language. I had no knowledge about lisp when I started to implement this.

Some people gave fruitful suggestions, comments with working codes to `manued.el` implementation. I will thank for all such people, especially the following people. (Alphabetical order)

- Ken-ich Suzuki (manuediff)
- Mikio Nakajima (bug fix etc. for version 0.9.3)
- Stefan Monnier (comments for version 0.9.1)
- Takao Kawamura (bug fix etc. for version 0.9.3)

## Bibliography

1
  Emacs and its Info (Emacs 20, XEmacs).

2
  TAKEUCHI Ikuo.
  Hajimete no hito no tame no LISP (LISP for beginners (in Japanese)).
  Saiensu-sha, 1986.

3
  TAKEUCHI Ikuo.
  Manuscript editing on email.
  39 th Programming Symposium in Japan, pages 61-68, January 1998.

4
  AOYAGI Takuta.
  UNIX Tanpen series Emacs Lisp (In Japanese).
  Kougakutosho, 1997.

5
  HIROSE Yuuji.
  Yasashii Emacs-Lisp kouza (In Japanese).
  Katto sisutemu, 1999.

## Index

# About this document ...

Manued Reference Manual

This document was generated using the LaTeX2`HTML` translator Version 2008 (1.71)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html `-html_version 4.0 -init_file dot.latex2html-init-eng manued-e.tex`

The translation was initiated by hitoshi on 2012-11-06