* emacs documentation
@ 2004-10-22 21:31 Tak Ota
2004-10-23 18:48 ` Richard Stallman
0 siblings, 1 reply; 20+ messages in thread
From: Tak Ota @ 2004-10-22 21:31 UTC (permalink / raw
Cc: pgeorgief
[-- Attachment #1: Type: Text/Plain, Size: 533 bytes --]
Hello,
Attached is a preliminary version of emacs document that describes how
to use lisp/textmodes/table.el package. It is written by Paul
Georgief based on my minimum documentation in the original lisp source
code.
Our intention is to place it as one of the subsections under "Commands
for Human Languages" section. Unfortunately neither Paul or I know
how to write texinfo source so the document is in plain ASCII text.
Could someone please compile it into texinfo source and incorporate
into man directory? Thank you.
-Tak
[-- Attachment #2: table.txt --]
[-- Type: Text/Plain, Size: 17384 bytes --]
Commands for Human Languages
* Text based Table:: Editing text based tables in WYSIWYG fashion.
Table mode provides an easy and intuitive way to create and edit WYSIWYG
text-based tables. Below is an example of such a table:
+-----------------+--------------------------------+-----------------+
| Command | Description | Key Binding |
+-----------------+--------------------------------+-----------------+
| forward-char |Move point right N characters | C-f |
| |(left if N is negative). | |
| | | |
| |On reaching end of buffer, stop | |
| |and signal error. | |
+-----------------+--------------------------------+-----------------+
| backward-char |Move point left N characters | C-b |
| |(right if N is negative). | |
| | | |
| |On attempt to pass beginning or | |
| |end of buffer, stop and signal | |
| |error. | |
+-----------------+--------------------------------+-----------------+
Table mode allows the contents of the above table to be easily manipulated by
inserting or deleting characters inside a cell. A cell is effectively a
localized rectangular edit region and edits to a cell do not affect the contets
of the surrounding cells. If the contents do not fit into a cell, then the cell
is automatically expanded in the vertical and/or horizontal directions and the
rest of the table is restructured and reformatted in accordance with the growth
of the cell.
* Menu:
* Definition:: What is a text based table.
Look at the following examples of valid tables as a reference while
you read this section:
+--+----+---+ +-+ +--+-----+
| | | | | | | | |
+--+----+---+ +-+ | +--+--+
| | | | | | | |
+--+----+---+ +--+--+ |
| | |
+-----+--+
A table consists of a rectangular frame and the contents inside the frame. A
table's cells must be at least one character wide and one character high with
two adjacent cells sharing a boarder line. A cell can be subdivided into
multiple rectangular cells but cannot nest or overlap.
Both the table frame and cell border lines must consist of one of three
special characters. The variables that hold these characters are described
below:
`table-cell-vertical-char' Holds the character used for vertical lines.
The default value is `|'.
`table-cell-horizontal-char' Holds the character used for horizontal
lines. The default value is `-'.
`table-cell-intersection-char' Holds the character used at where
horizontal line and vertical line meet.
The default value is `+'.
Based on this definition, the following five tables are examples of invalid
tables:
+-----+ +-----+ +--+ +-++--+ ++
| | | | | | | || | ++
| +-+ | | | | | | || |
| | | | +--+ | +--+--+ +-++--+
| +-+ | | | | | | | +-++--+
| | | | | | | | | || |
+-----+ +--+--+ +--+--+ +-++--+
(1) (2) (3) (4) (5)
>From left to right: 1) Nested cells are not allowed. 2) Overlapped cells or
nonrectangular cells are not allowed. 3) The border must be rectanglular.
4) Cells must have a minimum width/height of one character. 5) Same as 4.
* Table Creation:: How to create a table.
The command to create a table is `table-insert'. When called interactively
the function asks for the number of columns, number of rows, cell width and cell
height. The number of columns is a number of cells within the table's width.
The number of rows is the number of cells within the table's height. The cell
width is a number of characters that fit within a cell width. The cell height
is a number of lines within cell height. While the number of columns and number
of rows must be an integer number, the cell width and the cell height can be
either an integer number (when the value is constant across the table) or a
series of integer numbers, separated by space or comma, where each number
corresponds to each cell width within a row from left to right or each cell
height within a column from top to bottom.
`table-insert' Create and insert a table.
* Table Recognition:: How to activate and deactivate tables.
A table can be automatically recognized within an emacs buffer by issuing the
`table-recognize' command. Emacs scans the current buffer, recognizes valid
table cells, and attaches appropriate text properties to allow for table
editing. The converse operation, `table-unrecognize' is used to remove the special
text properties and revert the buffer back to plain text.
An optional numeric prefix argument can preceed the `table-recognize' command.
If this value is negative, tables in the buffer become inactive. This is
equivalent to issuing `table-unrecognize'.
Similar functions exist to: 1) Enable or disable tables within a region, 2)
Enable or disable individual tables, and 3) Enable individual cells. These
commands are given here:
`table-recognize-region' Recognizes tables within the current region and
activates them.
`table-unrecognize-region' Deactivates tables within the current region.
`table-recognize-table' Recognizes a table under point and activates it.
`table-unrecognize-table' Deactivates a table under point.
`table-recognize-cell' Recognizes a cell under point and activates it.
`table-unrecognize-cell' Deactivates a cell under point.
* Cell Operation:: Special operation in a table cell.
The command `table-forward-cell' and `table-backward-cell' move point from the
current cell to an adjacent cell forward and backward respectively. The order
of the cell is wrapped. When point is positioned in the last cell of a table,
issuing `table-forward-cell' moves point to the first cell in the table.
Likewise `table-backward-cell' from the first cell in a table moves point to the
last cell in the table.
The command `table-span-cell' spans the current cell into one of the four
directions - right, left, above or below - and merges the current cell with the
adjacent cell. It does not allow directions to which spanning does not produce
a legitimate cell.
The command `table-split-cell' splits the current cell vertically or
horizontally. This command is a wrapper to the direction specific commands
`table-split-cell-vertically' and `table-split-cell-horizontally'.
The command `table-split-cell-vertically' splits the current cell vertically
and creates a pair of cells above and below where point is located. The content
in the original cell is split as well.
The command `table-split-cell-horizontally' splits the current cell
horizontally and creates a pair of cells right and left of where point is
located. If the subject cell to split is not empty the user is asked how to
handle the cell contents. The three options are: `split', `left', or `right'.
`split' splits the contents at point literally while the `left' and `right' options
move the entire contents into the left or right cell respectively.
The next four commands enlarge or shrink a cell. These commands can take
numeric arguments (see Arguments) to specify how many columns or rows to enlarge
or shrink a particular table.
`table-heighten-cell' enlarges the current cell vertically.
`table-shorten-cell' shrinks the current cell vertically.
`table-widen-cell' enlarges the current cell horizontally.
`table-narrow-cell' shrinks the current cell horizontally.
* Cell Justification:: Justifying cell contents.
You can specify text justification for each cell. The justification
is remembered independently for each cell and the subsequent editing
of cell contents is subject to the specified justification.
The command `table-justify' requests the user to specify what to justify: a
`cell',`column', or `row'. The `cell' options sets the justification only to
the current cell. The `column' or `row' options set the justification to all
the cells within a column or row respectively. The command then requsts the
user to enter which justification to apply: `left', `center', `right', `top',
`middle', `bottom', or `none'. The options `left', `center' and `right' specify
horizontal justification while the options `top', `middle', `bottom' and 'none'
specify vertical justification. The vertical justification `none' effectively
removes vertical justification while horizontal justification must be one of
`left', `center' or `right'. Horizontal justification and vertical
justification are specified independently.
Justification information is stored in the buffer as a part of text property.
Therefore, this information is ephemeral and does not survive through the loss
of the buffer (closing the buffer and revisiting the buffer erase any previous
text properties). To alleviate this shortcoming the command `table-recognize'
and other recognition commands are equipped with a convenience feature (turned
on by default). During table recognition, the contents of a cell are examined
to determine which justification was originally applied to the cell and then
applies this justification to the the cell. This is a speculative algorithm and
is therefore not perfect, however, the justification is deduced correctly most
of the time. If you desire to disable this feature set nil to the customizable
variable `table-detect-cell-alignment'.
* Row Operation:: Manipulating Rows of table cell.
The command `table-insert-row' inserts a row of cells before the current row
in a table. The current row where point is located is pushed down after the
newly inserted row. When a numeric prefix argument is present it specifies the
number of rows to insert. Note that in order to insert rows after the last row
at the bottom of a table, point must be placed below the table, which is outside
of the table, prior to invoking this command.
The command `table-delete-row' deletes a row of cells at point. When
a numeric prefix argument is present it specifies the number of rows to
delete.
* Column Operation:: Manipulating Columns of table cell.
The command `table-insert-column' inserts a column of cells to the left of the
current row in a table. The current column where point is located at is pushed
right of the newly inserted column. To insert a column to the right side of the
right most column, point must be placed to the right side of the right most
column, which is outside of the table, prior to invoking this command.
A command `table-delete-column' deletes a column of cells at point. When a
numeric prefix argument is present it specifies the number of rows to delete.
* Fixed Width Mode:: Fixing cell width.
The command `table-fixed-width-mode' toggles fixed width mode on and off.
When the fixed width mode is turned on, editing inside a cell never changes the
cell width. In normal mode the cell width expands automatically in order to
prevent a word from being folded into multiple lines. As a default the fixed
width mode is turned off.
* Text/Table Conversion:: Converting between plain text and table.
The command `table-capture' captures plain text in a region and turn it into a
table. Unlike `table-recognize' the original text does not have a table
appearance but may hold a logical table structure. For example, some elements
separated by known patterns form a two dimensional structure which can be turned
into a table. Look at the numbers below. The numbers are horizontally
separated by a comma and vertically separated by a newline character.
1, 2, 3, 4
5, 6, 7, 8
, 9, 10
When `table-capture' is applied to the above three line region, the region can
be turned into the next table,
+-----+-----+-----+-----+
|1 |2 |3 |4 |
+-----+-----+-----+-----+
|5 |6 |7 |8 |
+-----+-----+-----+-----+
| |9 |10 | |
+-----+-----+-----+-----+
where `,' is used for a column delimiter egexp and a newline is used
for a row delimiter regexp and cells are left justified and minimum
cell width is 5.
The command `table-release' does the opposite of `table-capture'. It releases
a table by removing the table frame and cell borders. This leaves the table
contents as plain text. One of the useful applications of the combination
`table-capture' and `table-release' is to edit a text in layout. Look at the
following three paragraphs (the latter two are indented with header lines):
`table-capture' is a powerful command however mastering its power
requires some practice. Here is a list of items what it can do.
Parse Cell Items By using column delimiter regular
expression and raw delimiter regular
expression, it parses the specified text
area and extracts cell items from
non-table text and then forms a table out
of them.
Capture Text Area When no delimiters are specified it
creates a single cell table. The text in
the specified region is placed in that
cell.
Applying `table-capture' to a region containing the above three
paragraphs with empty strings for column delimiter regexps and row
delimiter regexp, creates a table with a single cell like the
following one.
+-----------------------------------------------------------------+
|`table-capture' is a powerful command however mastering its power|
|requires some practice. Here is a list of items what it can do. |
| |
|Parse Cell Items By using column delimiter regular |
| expression and raw delimiter regular |
| expression, it parses the specified text |
| area and extracts cell items from |
| non-table text and then forms a table out |
| of them. |
| |
|Capture Text Area When no delimiters are specified it |
| creates a single cell table. The text in |
| the specified region is placed in that |
| cell. |
+-----------------------------------------------------------------+
By splitting the cell appropriately we now have a table consisting of paragraphs
occupying its own cell. Each cell can now be edited independently without
affecting the layout of other cells.
+-----------------------------------------------------------------+
|`table-capture' is a powerful command however mastering its power|
|requires some practice. Here is a list of items what it can do. |
+---------------------+-------------------------------------------+
|Parse Cell Items |By using column delimiter regular |
| |expression and raw delimiter regular |
| |expression, it parses the specified text |
| |area and extracts cell items from |
| |non-table text and then forms a table out |
| |of them. |
+---------------------+-------------------------------------------+
|Capture Text Area |When no delimiters are specified it |
| |creates a single cell table. The text in |
| |the specified region is placed in that |
| |cell. |
+---------------------+-------------------------------------------+
By applying `table-release', which does the opposite process, the
contents become once again plain text. `table-release' works as
a companion command to `table-capture'.
* Measuring Table:: Analyzing table dimension.
The command `table-query-dimension' analyzes a table structure and
reports information regarding its dimension. In case of the above example
table, the output from the `table-query-dimension' is:
Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5
This indicates that the current cell is 21 character wide and 6 lines high, the
entire table is 67 characters wide end 16 lines hight. The table has 2 columns
and 3 rows. It has total of 5 cells since the first row has a spanned cell.
* Sequence of Cells:: Operation on sequence of cells.
The command `table-insert-sequence' inserts a string into each cell. Each
string is a part of a sequence i.e. a series of incrementing integer numbers.
* Source Generation:: Generating table source in a language.
`table-generate-source'
* Compatibility:: Potential issues with other modes.
[-- Attachment #3: Type: text/plain, Size: 142 bytes --]
_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: emacs documentation
2004-10-22 21:31 emacs documentation Tak Ota
@ 2004-10-23 18:48 ` Richard Stallman
2004-10-23 19:25 ` Eli Zaretskii
0 siblings, 1 reply; 20+ messages in thread
From: Richard Stallman @ 2004-10-23 18:48 UTC (permalink / raw
Cc: pgeorgief, Tak Ota
Would someone who knows Texinfo like to work on translating the
table.el documentation? It is only around 400 lines long--not
a very big job.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: emacs documentation
2004-10-23 18:48 ` Richard Stallman
@ 2004-10-23 19:25 ` Eli Zaretskii
2004-10-23 21:34 ` Eli Zaretskii
0 siblings, 1 reply; 20+ messages in thread
From: Eli Zaretskii @ 2004-10-23 19:25 UTC (permalink / raw
Cc: pgeorgief, Takaaki.Ota, emacs-devel
> From: Richard Stallman <rms@gnu.org>
> Date: Sat, 23 Oct 2004 14:48:39 -0400
> Cc: pgeorgief@ucsd.edu, Tak Ota <Takaaki.Ota@am.sony.com>
>
> Would someone who knows Texinfo like to work on translating the
> table.el documentation? It is only around 400 lines long--not
> a very big job.
I'll do it.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: emacs documentation
2004-10-23 19:25 ` Eli Zaretskii
@ 2004-10-23 21:34 ` Eli Zaretskii
0 siblings, 0 replies; 20+ messages in thread
From: Eli Zaretskii @ 2004-10-23 21:34 UTC (permalink / raw
Cc: pgeorgief, emacs-devel, rms, Takaaki.Ota
> Date: Sat, 23 Oct 2004 21:25:59 +0200
> From: "Eli Zaretskii" <eliz@gnu.org>
> Cc: pgeorgief@ucsd.edu, Takaaki.Ota@am.sony.com, emacs-devel@gnu.org
>
> > From: Richard Stallman <rms@gnu.org>
> > Date: Sat, 23 Oct 2004 14:48:39 -0400
> > Cc: pgeorgief@ucsd.edu, Tak Ota <Takaaki.Ota@am.sony.com>
> >
> > Would someone who knows Texinfo like to work on translating the
> > table.el documentation? It is only around 400 lines long--not
> > a very big job.
>
> I'll do it.
Done. Below is the Texinfo source that I added to the end of
text.texi and committed the result. Please and modify at will.
@node Text Based Tables
@section Editing Text-based Tables
@cindex table mode
@cindex text-based tables
Table Mode provides an easy and intuitive way to create and edit WYSIWYG
text-based tables. Here is an example of such a table:
@smallexample
+-----------------+--------------------------------+-----------------+
| Command | Description | Key Binding |
+-----------------+--------------------------------+-----------------+
| forward-char |Move point right N characters | C-f |
| |(left if N is negative). | |
| | | |
| |On reaching end of buffer, stop | |
| |and signal error. | |
+-----------------+--------------------------------+-----------------+
| backward-char |Move point left N characters | C-b |
| |(right if N is negative). | |
| | | |
| |On attempt to pass beginning or | |
| |end of buffer, stop and signal | |
| |error. | |
+-----------------+--------------------------------+-----------------+
@end smallexample
Table Mode allows the contents of the table such as this one to be
easily manipulated by inserting or deleting characters inside a cell.
A cell is effectively a localized rectangular edit region and edits to
a cell do not affect the contents of the surrounding cells. If the
contents do not fit into a cell, then the cell is automatically
expanded in the vertical and/or horizontal directions and the rest of
the table is restructured and reformatted in accordance with the
growth of the cell.
@menu
* Table Definition:: What is a text based table.
* Table Creation:: How to create a table.
* Table Recognition:: How to activate and deactivate tables.
* Cell Commands:: Cell-oriented commands in a table.
* Cell Justification:: Justifying cell contents.
* Row Commands:: Manipulating rows of table cell.
* Column Commands:: Manipulating columns of table cell.
* Fixed Width Mode:: Fixing cell width.
* Table Conversion:: Converting between plain text and tables.
* Measuring Tables:: Analyzing table dimension.
* Table Misc:: Table miscellany.
@end menu
@node Table Definition
@subsection What is a Text-based Table?
Look at the following examples of valid tables as a reference while
you read this section:
@example
+--+----+---+ +-+ +--+-----+
| | | | | | | | |
+--+----+---+ +-+ | +--+--+
| | | | | | | |
+--+----+---+ +--+--+ |
| | |
+-----+--+
@end example
A table consists of a rectangular frame and the contents inside the
frame. A table's cells must be at least one character wide and one
character high with two adjacent cells sharing a boarder line. A cell
can be subdivided into multiple rectangular cells but cannot nest or
overlap.
Both the table frame and cell border lines must consist of one of
three special characters. The variables that hold these characters
are described below:
@table @code
@vindex table-cell-vertical-char
@item table-cell-vertical-char
Holds the character used for vertical lines. The default value is
@samp{|}.
@vindex table-cell-horizontal-char
@item table-cell-horizontal-char
Holds the character used for horizontal lines. The default value is
@samp{-}.
@vindex table-cell-intersection-char
@item table-cell-intersection-char
Holds the character used at where horizontal line and vertical line
meet. The default value is @samp{+}.
@end table
@noindent
Based on this definition, the following five tables are examples of invalid
tables:
@example
+-----+ +-----+ +--+ +-++--+ ++
| | | | | | | || | ++
| +-+ | | | | | | || |
| | | | +--+ | +--+--+ +-++--+
| +-+ | | | | | | | +-++--+
| | | | | | | | | || |
+-----+ +--+--+ +--+--+ +-++--+
a b c d e
@end example
>From left to right:
@enumerate a
@item
Nested cells are not allowed.
@item
Overlapped cells or non-rectangular cells are not allowed.
@item
The border must be rectangular.
@item
Cells must have a minimum width/height of one character.
@item
Same as d.
@end enumerate
@node Table Creation
@subsection How to Create a Table?
@cindex create a text-based table
@cindex table creation
@findex table-insert
The command to create a table is @code{table-insert}. When called
interactively, it asks for the number of columns, number of rows, cell
width and cell height. The number of columns is a number of cells
within the table's width. The number of rows is the number of cells
within the table's height. The cell width is a number of characters
that fit within a cell width. The cell height is a number of lines
within cell height. While the number of columns and number of rows
must be an integer number, the cell width and the cell height can be
either an integer number (when the value is constant across the table)
or a series of integer numbers, separated by spaces or commas, where
each number corresponds to each cell width within a row from left to
right or each cell height within a column from top to bottom.
@node Table Recognition
@subsection Table Recognition
@cindex table recognition
@findex table-recognize
@findex table-unrecognize
Table Mode maintains special text properties in the buffer to allow
editing in a convenient fashion. When a buffer with tables is saved
to its file, these text properties are lost, so when you visit this
file again later, Emacs does not see a table, but just formatted text.
To resurrect the table text properties, issue the @kbd{M-x
table-recognize} command. It scans the current buffer, recognizes
valid table cells, and attaches appropriate text properties to allow
for table editing. The converse command, @code{table-unrecognize}, is
used to remove the special text properties and revert the buffer back
to plain text.
An optional numeric prefix argument can precede the
@code{table-recognize} command. If the argument is negative, tables
in the buffer become inactive. This is equivalent to invoking
@code{table-unrecognize}.
Similar functions exist to enable or disable tables within a region,
enable or disable individual tables, and enable/disable individual
cells. These commands are:
@table @kbd
@findex table-recognize-region
@item M-x table-recognize-region
Recognize tables within the current region and activate them.
@findex table-unrecognize-region
@item M-x table-unrecognize-region
Deactivate tables within the current region.
@findex table-recognize-table
@item M-x table-recognize-table
Recognize the table under point and activate it.
@findex table-unrecognize-table
@item M-x table-unrecognize-table
Deactivate the table under point.
@findex table-recognize-cell
@item M-x table-recognize-cell
Recognize the cell under point and activate it.
@findex table-unrecognize-cell
@item M-x table-unrecognize-cell
Deactivate the cell under point.
@end table
For another way of converting text into tables, see @ref{Table
Conversion}.
@node Cell Commands
@subsection Commands for Table Cells
@findex table-forward-cell
@findex table-backward-cell
The commands @code{table-forward-cell} and
@code{table-backward-cell} move point from the current cell to an
adjacent cell forward and backward respectively. The order of the
cell is wrapped. When point is positioned in the last cell of a
table, typing @kbd{M-x table-forward-cell} moves point to the first
cell in the table. Likewise @kbd{M-x table-backward-cell} from the
first cell in a table moves point to the last cell in the table.
@findex table-span-cell
The command @code{table-span-cell} spans the current cell into one
of the four directions---right, left, above or below---and merges the
current cell with the adjacent cell. It does not allow directions to
which spanning does not produce a legitimate cell.
@findex table-split-cell
@cindex text-based tables, split a cell
@cindex split table cell
The command @code{table-split-cell} splits the current cell
vertically or horizontally. This command is a wrapper to the
direction specific commands @code{table-split-cell-vertically} and
@code{table-split-cell-horizontally}.
@findex table-split-cell-vertically
The command @code{table-split-cell-vertically} splits the current
cell vertically and creates a pair of cells above and below where
point is located. The content in the original cell is split as well.
@findex table-split-cell-horizontally
The command @code{table-split-cell-horizontally} splits the current
cell horizontally and creates a pair of cells right and left of where
point is located. If the subject cell to split is not empty the user
is asked how to handle the cell contents. The three options are:
@code{split}, @code{left}, or @code{right}. @code{split} splits the
contents at point literally while the @code{left} and @code{right}
options move the entire contents into the left or right cell
respectively.
@cindex enlarge a table cell
@cindex shrink a table cell
The next four commands enlarge or shrink a cell. These commands
accept numeric arguments (@pxref{Arguments}) to specify how many
columns or rows to enlarge or shrink a particular table.
@table @kbd
@findex table-heighten-cell
@item M-x table-heighten-cell
Enlarge the current cell vertically.
@findex table-shorten-cell
@item M-x table-shorten-cell
Shrink the current cell vertically.
@findex table-widen-cell
@item M-x table-widen-cell
Enlarge the current cell horizontally.
@findex table-narrow-cell
@item M-x table-narrow-cell
Shrink the current cell horizontally.
@end table
@node Cell Justification
@subsection Cell Justification
@cindex cell text justification
You can specify text justification for each cell. The justification
is remembered independently for each cell and the subsequent editing
of cell contents is subject to the specified justification.
@findex table-justify
The command @code{table-justify} requests the user to specify what
to justify: a cell,a column, or a row. If you select cell
justification, this command sets the justification only to the current
cell. Selecting column or row justification set the justification to
all the cells within a column or row respectively. The command then
requests the user to enter which justification to apply: @code{left},
@code{center}, @code{right}, @code{top}, @code{middle}, @code{bottom},
or @code{none}. The options @code{left}, @code{center}, and
@code{right} specify horizontal justification while the options
@code{top}, @code{middle}, @code{bottom}, and @code{none} specify
vertical justification. The vertical justification @code{none}
effectively removes vertical justification while horizontal
justification must be one of @code{left}, @code{center}, or
@code{right}. Horizontal justification and vertical justification are
specified independently.
@vindex table-detect-cell-alignment
Justification information is stored in the buffer as a part of text
property. Therefore, this information is ephemeral and does not
survive through the loss of the buffer (closing the buffer and
revisiting the buffer erase any previous text properties). To
countermand for this, the command @code{table-recognize} and other
recognition commands (@pxref{Table Recognition}) are equipped with a
convenience feature (turned on by default). During table recognition,
the contents of a cell are examined to determine which justification
was originally applied to the cell and then applies this justification
to the the cell. This is a speculative algorithm and is therefore not
perfect, however, the justification is deduced correctly most of the
time. If you desire to disable this feature, customize the variable
@code{table-detect-cell-alignment} to set it to @code{nil}.
@node Row Commands
@subsection Commands for Table Rows
@cindex table row commands
@cindex insert row in table
@findex table-insert-row
The command @code{table-insert-row} inserts a row of cells before
the current row in a table. The current row where point is located is
pushed down after the newly inserted row. A numeric prefix argument
specifies the number of rows to insert. Note that in order to insert
rows @emph{after} the last row at the bottom of a table, you must
place point below the table, i.e.@: outside the table, prior to
invoking this command.
@cindex delete row in table
@findex table-delete-row
The command @code{table-delete-row} deletes a row of cells at point.
A numeric prefix argument specifies the number of rows to delete.
@node Column Commands
@subsection Commands for Table Columns
@cindex table column commands
@cindex insert column in table
@findex table-insert-column
The command @code{table-insert-column} inserts a column of cells to
the left of the current row in a table. The current column where
point is located at is pushed right of the newly inserted column. To
insert a column to the right side of the right most column, place
point to the right of the rightmost column, which is outside of the
table, prior to invoking this command. A numeric prefix argument
specifies the number of columns to insert.
@cindex delete column in table
A command @code{table-delete-column} deletes a column of cells at
point. A numeric prefix argument specifies the number of columns to
delete.
@node Fixed Width Mode
@subsection Fix Width of Cells
@cindex fix width of table cells
@findex table-fixed-width-mode
The command @code{table-fixed-width-mode} toggles fixed width mode
on and off. When the fixed width mode is turned on, editing inside a
cell never changes the cell width; when it is off, the cell width
expands automatically in order to prevent a word from being folded
into multiple lines. By default, the fixed width mode is turned off.
@node Table Conversion
@subsection Conversion Between Plain Text and Tables
@cindex text to table
@cindex table to text
@findex table-capture
The command @code{table-capture} captures plain text in a region and
turns it into a table. Unlike @code{table-recognize} (@pxref{Table
Recognition}), the original text does not have a table appearance but
may hold a logical table structure. For example, some elements
separated by known patterns form a two dimensional structure which can
be turned into a table. Look at the numbers below. The numbers are
horizontally separated by a comma and vertically separated by a
newline character.
@example
1, 2, 3, 4
5, 6, 7, 8
, 9, 10
@end example
@noindent
When you invoke @kbd{M-x table-capture} on the above three-line
region, the region can be turned into the next table:
@example
+-----+-----+-----+-----+
|1 |2 |3 |4 |
+-----+-----+-----+-----+
|5 |6 |7 |8 |
+-----+-----+-----+-----+
| |9 |10 | |
+-----+-----+-----+-----+
@end example
@noindent
where @samp{,} is used for a column delimiter regexp, a newline is
used for a row delimiter regexp, cells are left justified, and minimum
cell width is 5.
@findex table-release
The command @code{table-release} does the opposite of
@code{table-capture}. It releases a table by removing the table frame
and cell borders. This leaves the table contents as plain text. One
of the useful applications of @code{table-capture} and
@code{table-release} is to edit a text in layout. Look at the
following three paragraphs (the latter two are indented with header
lines):
@example
@samp{table-capture} is a powerful command however mastering its power
requires some practice. Here is a list of items what it can do.
Parse Cell Items By using column delimiter regular
expression and raw delimiter regular
expression, it parses the specified text
area and extracts cell items from
non-table text and then forms a table out
of them.
Capture Text Area When no delimiters are specified it
creates a single cell table. The text in
the specified region is placed in that
cell.
@end example
@noindent
Applying @code{table-capture} to a region containing the above three
paragraphs, with empty strings for column delimiter regexp and row
delimiter regexp, creates a table with a single cell like the
following one.
@c The first line's right-hand frame in the following two examples
@c sticks out to accommodate for the removal of @samp in the
@c produced output!!
@example
+-----------------------------------------------------------------+
|@samp{table-capture} is a powerful command however mastering its |
|power requires some practice. Here is a list of items what it |
|can do. |
| |
|Parse Cell Items By using column delimiter regular |
| expression and raw delimiter regular |
| expression, it parses the specified text |
| area and extracts cell items from |
| non-table text and then forms a table out |
| of them. |
| |
|Capture Text Area When no delimiters are specified it |
| creates a single cell table. The text in |
| the specified region is placed in that |
| cell. |
+-----------------------------------------------------------------+
@end example
@noindent
By splitting the cell appropriately we now have a table consisting of
paragraphs occupying its own cell. Each cell can now be edited
independently without affecting the layout of other cells.
@example
+-----------------------------------------------------------------+
|@samp{table-capture} is a powerful command however mastering its |
|power requires some practice. Here is a list of items what it |
|can do. |
+---------------------+-------------------------------------------+
|Parse Cell Items |By using column delimiter regular |
| |expression and raw delimiter regular |
| |expression, it parses the specified text |
| |area and extracts cell items from |
| |non-table text and then forms a table out |
| |of them. |
+---------------------+-------------------------------------------+
|Capture Text Area |When no delimiters are specified it |
| |creates a single cell table. The text in |
| |the specified region is placed in that |
| |cell. |
+---------------------+-------------------------------------------+
@end example
@noindent
By applying @code{table-release}, which does the opposite process, the
contents become once again plain text. @code{table-release} works as
a companion command to @code{table-capture}.
@node Measuring Tables
@subsection Analyzing Table Dimensions
@cindex table dimensions
@findex table-query-dimension
The command @code{table-query-dimension} analyzes a table structure
and reports information regarding its dimensions. In case of the
above example table, the @code{table-query-dimension} command displays
in echo area:
@smallexample
Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5
@end smallexample
@noindent
This indicates that the current cell is 21 character wide and 6 lines
high, the entire table is 67 characters wide and 16 lines high. The
table has 2 columns and 3 rows. It has a total of 5 cells, since the
first row has a spanned cell.
@node Table Misc
@subsection Table Miscellany
@cindex insert string into table cells
@findex table-insert-sequence
The command @code{table-insert-sequence} inserts a string into each
cell. Each string is a part of a sequence i.e.@: a series of
increasing integer numbers.
@cindex table in language format
@cindex table for HTML and LaTeX
@findex table-generate-source
The command @code{table-generate-source} generates a table formatted
for a specific markup language. It asks for a language (which must be
one of @code{html}, @code{latex}, or @code{cals}), a destination
buffer where to put the result, and the table caption (a string), and
then inserts the generated table in the proper syntax into the
destination buffer. The default destination buffer is
@code{table.@var{lang}}, where @var{lang} is the language you
specified.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Emacs documentation.
2007-09-23 11:35 ` Dave Pawson
@ 2007-09-29 15:46 ` Alan Mackenzie
2007-09-29 15:47 ` Dave Pawson
2007-09-29 16:33 ` Eli Zaretskii
0 siblings, 2 replies; 20+ messages in thread
From: Alan Mackenzie @ 2007-09-29 15:46 UTC (permalink / raw
To: Dave Pawson; +Cc: help-gnu-emacs
Hi, Dave!
On Sun, Sep 23, 2007 at 12:35:05PM +0100, Dave Pawson wrote:
> On 23/09/2007, Bastien <bzg@altern.org> wrote:
> > "Dave Pawson" <dave.pawson@gmail.com> writes:
> > > My offer is to convert the emacs documentation into docbook, version 5
> > > and work with those interested to improve it/bring it up to scratch.
> > It would be like trying to convert man pages into docbook. Why?
> Because XML is more flexible and a more modern standard for
> documentation IMHO.
Assembler is more flexible than C, but nobody nowadays uses assembler
very much. Being "more modern" has never been a compelling argument for
anything in Emacs. The question to ask is "is it any good?".
XML isn't any good as a source format; it's designed to be parseable by
programs with minimum effort, and places no value on being readable or
writeable. Using XML/Docbook as a source language would be taking a
step back to 1960s technology:
(i) There is nothing like Texinfo's "@" or Lisp's/C's "\" for escape
purposes; you've got to write "<" as "<", much like you had to write
".lt." in Fortran. "ü" (German "u umlaut") appears as "ü". And so
on. Yuck! That stuff isn't unreadable, but it's uncomfortably close,
and it's clumsy enough to condemn XML.
(ii) Instead of using single character block delimiters like "{}" in C
or "()" in Lisp, XML uses long, long keywords, e.g.
"<VeryLongUnreadableDelimiter>" to open a block and
"</VeryLongUnreadableDelimiter>" to close it. This harks back to
Algol's and Pascal's "BEGIN" and "END". It also reduces the readability
and signal to noise ratio horribly. Hackers detest prolixity. ;-)
(iii) You can't just comment out a block of XML. Doing so make the
source syntactically incorrect. In fact, XML comments have a rigid
syntactic structure which stops you describing XML constructs in them.
I think this snag, in itself, rules out XML/Docbook as a sensible source
format.
(iv) This one might just be me, but I find "<" and ">" as delimiters far
too jaggy and violent (except for occasional use, as in C's "#include
<stdio.h>" or a C++/Java template).
> > I guess too many developpers actually use Texinfo to document their
> > code, and both users and developpers seem to be happy with that.
> You may be right. I think it is worth challenging though, otherwise
> we'll never progress?
XML as a source language isn't progress; it's like regressing into the
dark ages. I suspect most Docbook writers actually use special purpose
editors to create their source code, rather than Emacs or vi. This is
anathema to Emacs developers. If we changed our default format from
.texi to .xml, I'd probably just give up hacking documentation - it'd be
too painful.
I'm not saying that Texinfo is ideal, and maybe we could use a better
format. But XML isn't it.
> --
> Dave Pawson
--
Alan Mackenzie (Ittersbach, Germany).
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Emacs documentation.
2007-09-29 15:46 ` Emacs documentation Alan Mackenzie
@ 2007-09-29 15:47 ` Dave Pawson
2007-09-29 16:03 ` Peter Dyballa
2007-09-29 19:42 ` Alan Mackenzie
2007-09-29 16:33 ` Eli Zaretskii
1 sibling, 2 replies; 20+ messages in thread
From: Dave Pawson @ 2007-09-29 15:47 UTC (permalink / raw
To: Alan Mackenzie; +Cc: help-gnu-emacs
[-- Attachment #1: Type: text/plain, Size: 2718 bytes --]
On 29/09/2007, Alan Mackenzie <acm@muc.de> wrote:
>
> > Because XML is more flexible and a more modern standard for
> > documentation IMHO.
>
> Assembler is more flexible than C, but nobody nowadays uses assembler
> very much. Being "more modern" has never been a compelling argument for
> anything in Emacs. The question to ask is "is it any good?".
Yes. Look around.
>
> XML isn't any good as a source format; it's designed to be parseable by
> programs with minimum effort, and places no value on being readable or
> writeable. Using XML/Docbook as a source language would be taking a
> step back to 1960s technology:
Rubbish.
>
> (i) There is nothing like Texinfo's "@" or Lisp's/C's "\" for escape
> purposes; you've got to write "<" as "<", much like you had to write
> ".lt." in Fortran. "ü" (German "u umlaut") appears as "ü". And so
> on. Yuck! That stuff isn't unreadable, but it's uncomfortably close,
> and it's clumsy enough to condemn XML.
Go play catchup Alan. You're years behind. About ten.
>
> (ii) Instead of using single character block delimiters like "{}" in C
> or "()" in Lisp, XML uses long, long keywords, e.g.
> "<VeryLongUnreadableDelimiter>" to open a block and
> "</VeryLongUnreadableDelimiter>" to close it. This harks back to
> Algol's and Pascal's "BEGIN" and "END". It also reduces the readability
> and signal to noise ratio horribly. Hackers detest prolixity. ;-)
It's called semantic markup.
>
> (iii) You can't just comment out a block of XML.
Wrong.
> Doing so make the
> source syntactically incorrect. In fact, XML comments have a rigid
> syntactic structure which stops you describing XML constructs in them.
> I think this snag, in itself, rules out XML/Docbook as a sensible source
> format.
Where have you been?
>
> (iv) This one might just be me, but I find "<" and ">" as delimiters far
> too jaggy and violent (except for occasional use, as in C's "#include
> <stdio.h>" or a C++/Java template).
It's just you.
>
> > > I guess too many developpers actually use Texinfo to document their
> > > code, and both users and developpers seem to be happy with that.
Let's agree to differ on that.
>
> > You may be right. I think it is worth challenging though, otherwise
> > we'll never progress?
>
> XML as a source language isn't progress; it's like regressing into the
> dark ages.
Go ask around the OSS world what's being used for documentation.
> I suspect most Docbook writers actually use special purpose
> editors to create their source code, rather than Emacs or vi.
Emacs has done for me for the last ten years.
> I'm not saying that Texinfo is ideal,
Oh good.
--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk
[-- Attachment #2: Type: text/plain, Size: 152 bytes --]
_______________________________________________
help-gnu-emacs mailing list
help-gnu-emacs@gnu.org
http://lists.gnu.org/mailman/listinfo/help-gnu-emacs
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Emacs documentation.
2007-09-29 15:47 ` Dave Pawson
@ 2007-09-29 16:03 ` Peter Dyballa
2007-09-29 19:42 ` Alan Mackenzie
1 sibling, 0 replies; 20+ messages in thread
From: Peter Dyballa @ 2007-09-29 16:03 UTC (permalink / raw
To: Dave Pawson; +Cc: help-gnu-emacs
Am 29.09.2007 um 17:47 schrieb Dave Pawson:
>>
>> XML isn't any good as a source format; it's designed to be
>> parseable by
>> programs with minimum effort, and places no value on being
>> readable or
>> writeable. Using XML/Docbook as a source language would be taking a
>> step back to 1960s technology:
>
> Rubbish.
Can't you sleep just one night over it? This is what I learned from
military service.
>>
>> (ii) Instead of using single character block delimiters like "{}"
>> in C
>> or "()" in Lisp, XML uses long, long keywords, e.g.
>> "<VeryLongUnreadableDelimiter>" to open a block and
>> "</VeryLongUnreadableDelimiter>" to close it. This harks back to
>> Algol's and Pascal's "BEGIN" and "END". It also reduces the
>> readability
>> and signal to noise ratio horribly. Hackers detest prolixity. ;-)
>
> It's called semantic markup.
How about usable markup?
--
Mit friedvollen Grüßen
Pete
"Give a man a fish, and you've fed him for a day. Teach him to fish,
and you've depleted the lake."
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Emacs documentation.
2007-09-29 15:46 ` Emacs documentation Alan Mackenzie
2007-09-29 15:47 ` Dave Pawson
@ 2007-09-29 16:33 ` Eli Zaretskii
1 sibling, 0 replies; 20+ messages in thread
From: Eli Zaretskii @ 2007-09-29 16:33 UTC (permalink / raw
To: help-gnu-emacs
> Date: Sat, 29 Sep 2007 15:46:01 +0000
> From: Alan Mackenzie <acm@muc.de>
> Cc: help-gnu-emacs@gnu.org
>
> I suspect most Docbook writers actually use special purpose editors
> to create their source code, rather than Emacs or vi.
I think the real reason is that, in professional book publishing
business, many editorial and other auxiliary tools speak Docbook. I'm
quite sure I've heard this in the past from someone who published
several books (and needed makeinfo's Docbook output feature for that
very reason).
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Emacs documentation.
2007-09-29 15:47 ` Dave Pawson
2007-09-29 16:03 ` Peter Dyballa
@ 2007-09-29 19:42 ` Alan Mackenzie
1 sibling, 0 replies; 20+ messages in thread
From: Alan Mackenzie @ 2007-09-29 19:42 UTC (permalink / raw
To: Dave Pawson; +Cc: help-gnu-emacs
Hi again, Dave!
>On 29/09/2007, Alan Mackenzie <address@hidden> wrote:
>>> Because XML is more flexible and a more modern standard for
>>> documentation IMHO.
>> Assembler is more flexible than C, but nobody nowadays uses assembler
>> very much. Being "more modern" has never been a compelling argument for
>> anything in Emacs. The question to ask is "is it any good?".
>Yes. Look around.
I have. I once had to hack an XML config file and I've amended some
Docbook source code, though it was some while ago. They were both
horrible.
What's so good about XML/Docbook as a source format?
>> XML isn't any good as a source format; it's designed to be parseable by
>> programs with minimum effort, and places no value on being readable or
>> writeable. Using XML/Docbook as a source language would be taking a
>> step back to 1960s technology:
>Rubbish.
:-)
>> (i) There is nothing like Texinfo's "@" or Lisp's/C's "\" for escape
>> purposes; you've got to write "<" as "<", much like you had to
>> write ".lt." in Fortran. "ü" (German "u umlaut") appears as
>> "ü". And so on. Yuck! That stuff isn't unreadable, but it's
>> uncomfortably close, and it's clumsy enough to condemn XML.
>Go play catchup Alan. You're years behind. About ten.
Oh good! So please correct my misapprehension and tell me what the
Docbook escape character is. Next, please tell me how to write a "<"
and a "ü" in a modern Docbook source. At any stage, you're more than
welcome to attempt to persuade me that writing Docbook source is easy,
pleasant and productive. Thanks in advance!
>> (ii) Instead of using single character block delimiters like "{}" in
>> C or "()" in Lisp, XML uses long, long keywords, e.g.
>> "<VeryLongUnreadableDelimiter>" to open a block and
>> "</VeryLongUnreadableDelimiter>" to close it. This harks back to
>> Algol's and Pascal's "BEGIN" and "END". It also reduces the
>> readability and signal to noise ratio horribly. Hackers detest
>> prolixity. ;-)
>It's called semantic markup.
It doesn't matter what it's called. The important point is that it's
difficult to read and likely difficult to write - much more so than the
Texinfo equivalents.
>> (iii) You can't just comment out a block of XML.
>Wrong.
Oh good! Please tell me how "just" to comment out a block of XML, with
emphasis on the word "just". I seem to remember Emacs in SGML mode
going through the region being commented, replacing all the "--"s with
"-/-", and not being able to reverse that transformation. That's unjust
indeed.
>> Doing so makes the source syntactically incorrect. In fact, XML
>> comments have a rigid syntactic structure which stops you describing
>> XML constructs in them. I think this snag, in itself, rules out
>> XML/Docbook as a sensible source format.
>Where have you been?
In XM hell.
[ .... ]
>> > You may be right. I think it is worth challenging though, otherwise
>> > we'll never progress?
>> XML as a source language isn't progress; it's like regressing into the
>> dark ages.
>Go ask around the OSS world what's being used for documentation.
Why? The fact that vast numbers of people use or have used Microsoft
Windows or XML or Cobol or Emacs or VHS videotape or Trabant cars or
variable length character encodings or Docbook or Fortran has no bearing
on whether these things are any good, or what they are good for.
I'm not sure you've thought this issue through. Popularity doesn't imply
quality. XML-based thingies and Microsoft Word (*.doc) are both widely
used formats, yet at least half of them are bad formats. As a Docbook
enthusiast, you should be able to counter my posts by arguing the
intrinsic merits of Docbook/XML, and why it would be superior to Texinfo
in the Emacs project. I haven't seen you doing this.
>> I suspect most Docbook writers actually use special purpose
>> editors to create their source code, rather than Emacs or vi.
>Emacs has done for me for the last ten years.
Do most Docbook writers use special purpose editors or don't they?
>--
>Dave Pawson
--
Alan Mackenzie (Ittersbach, Germany).
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Emacs documentation.
[not found] <mailman.1485.1191094713.18990.help-gnu-emacs@gnu.org>
@ 2007-09-29 20:01 ` David Kastrup
2007-09-29 22:04 ` Alan Mackenzie
[not found] ` <mailman.1488.1191103233.18990.help-gnu-emacs@gnu.org>
0 siblings, 2 replies; 20+ messages in thread
From: David Kastrup @ 2007-09-29 20:01 UTC (permalink / raw
To: help-gnu-emacs
Alan Mackenzie <acm@muc.de> writes:
> Hi again, Dave!
>
>>Go ask around the OSS world what's being used for documentation.
>
> Why?
Because you'll find that any XML-based process would be rather unusual
(at least ouside of the Java world). Man-pages, hand-written HTML,
plain text files, Texinfo, LaTeX and other stuff are more prevalent.
> The fact that vast numbers of people use or have used Microsoft
> Windows or XML or Cobol or Emacs or VHS videotape or Trabant cars or
> variable length character encodings or Docbook or Fortran has no
> bearing on whether these things are any good, or what they are good
> for.
The long dampeners on Trabant were actually a good complement to the
lousy road quality in the GDR. Imported cars suffered from a higher
probability of breakdowns because they were less well suited to the
potholes there.
> I'm not sure you've thought this issue through. Popularity doesn't
> imply quality. XML-based thingies and Microsoft Word (*.doc) are
> both widely used formats, yet at least half of them are bad formats.
> As a Docbook enthusiast, you should be able to counter my posts by
> arguing the intrinsic merits of Docbook/XML, and why it would be
> superior to Texinfo in the Emacs project. I haven't seen you doing
> this.
Well, he did personally inform me that he put me in his killfile when
I made a list of detailed problems and tried to elicit comments. So
that is one way of addressing such points.
>>> I suspect most Docbook writers actually use special purpose
>>> editors to create their source code, rather than Emacs or vi.
>
>>Emacs has done for me for the last ten years.
>
> Do most Docbook writers use special purpose editors or don't they?
To be fair: people using Emacs _are_ generally using a special purpose
editor (in the form of a good major mode). Even LaTeX is not
uncommonly written with special purpose editors and modes.
So if you want to get more relevant numbers, you probably should ask
on some vi user group, as that sort of editor can't be tailored as
well to the task. How many of those would write Texinfo and LaTeX
with their favorite general purpose editor, but revert to special
systems for XML writing?
I suppose still some, but have no hard numbers.
--
David Kastrup, Kriemhildstr. 15, 44793 Bochum
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Emacs documentation.
@ 2007-09-29 21:10 martin rudalics
0 siblings, 0 replies; 20+ messages in thread
From: martin rudalics @ 2007-09-29 21:10 UTC (permalink / raw
To: acm; +Cc: help-gnu-emacs
> ... or Trabant cars ...
Alan, you're exaggerating. Trabis were not that bad.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Emacs documentation.
2007-09-29 20:01 ` David Kastrup
@ 2007-09-29 22:04 ` Alan Mackenzie
2007-09-29 22:05 ` Tom Tromey
[not found] ` <mailman.1488.1191103233.18990.help-gnu-emacs@gnu.org>
1 sibling, 1 reply; 20+ messages in thread
From: Alan Mackenzie @ 2007-09-29 22:04 UTC (permalink / raw
To: David Kastrup; +Cc: help-gnu-emacs
'nAbend, David!
On Sat, Sep 29, 2007 at 10:01:40PM +0200, David Kastrup wrote:
>looked at Alan Mackenzie <acm@muc.de> writes:
> >>Go ask around the OSS world what's being used for documentation.
> > Why?
> Because you'll find that any XML-based process would be rather unusual
> (at least ouside of the Java world). Man-pages, hand-written HTML,
> plain text files, Texinfo, LaTeX and other stuff are more prevalent.
That's what I would've thought. Given the existence of, in particular,
TeX and LaTeX, I really don't understand what the point of Docbook is.
(That's NOT a rhetorical comment.)
What has irritated me about David P.'s posts is he seems to assume that
Docbook doesn't need justification - it is the Right Thing for any
documentation application, and it is somehow not done to ask questions
about it. I'm still hoping he'll come back with some answers.
[ .... ]
> The long dampeners on Trabant were actually a good complement to the
> lousy road quality in the GDR. Imported cars suffered from a higher
> probability of breakdowns because they were less well suited to the
> potholes there.
How things have changed since 1989!
[ .... ]
> >>> I suspect most Docbook writers actually use special purpose
> >>> editors to create their source code, rather than Emacs or vi.
> >>Emacs has done for me for the last ten years.
> > Do most Docbook writers use special purpose editors or don't they?
> To be fair: people using Emacs _are_ generally using a special purpose
> editor (in the form of a good major mode). Even LaTeX is not
> uncommonly written with special purpose editors and modes.
I didn't express myself very well. I think what I meant by "special
purpose editor" was one that interprets the XML data structure and hides
it from the user, much like Open Office does with ODF. I contrast this
with an editor where you actually see and edit the raw XML file, possibly
with the help of a good major mode. I suppose it's analogous to the
difference between editing Elisp source files and hacking through the
internal form created by the Lisp reader.
I don't think that Emacs developers would be willing to learn such a
special purpose editor, just to write Info-MkII documents with.
> So if you want to get more relevant numbers, you probably should ask
> on some vi user group, as that sort of editor can't be tailored as
> well to the task. How many of those would write Texinfo and LaTeX
> with their favorite general purpose editor, but revert to special
> systems for XML writing?
> I suppose still some, but have no hard numbers.
Nor me.
> David Kastrup, Kriemhildstr. 15, 44793 Bochum
--
Alan Mackenzie (Ittersbach, Germany).
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Emacs documentation.
2007-09-29 22:04 ` Alan Mackenzie
@ 2007-09-29 22:05 ` Tom Tromey
2007-09-30 2:18 ` Drew Adams
0 siblings, 1 reply; 20+ messages in thread
From: Tom Tromey @ 2007-09-29 22:05 UTC (permalink / raw
To: help-gnu-emacs
>>>>> "Alan" == Alan Mackenzie <acm@muc.de> writes:
Alan> I didn't express myself very well. I think what I meant by
Alan> "special purpose editor" was one that interprets the XML data
Alan> structure and hides it from the user, much like Open Office does
Alan> with ODF.
This is sort of a diversion, but I've heard talk from time to time
about writing such an editor as an Emacs mode. As an existing
example, there's `enriched.el'. (Open etc/enriched.doc for an
example, or look at it with find-file-literally to see the contents as
they appear on disk.)
A full ODF editor would be a major undertaking.
Tom
^ permalink raw reply [flat|nested] 20+ messages in thread
* RE: Emacs documentation.
2007-09-29 22:05 ` Tom Tromey
@ 2007-09-30 2:18 ` Drew Adams
0 siblings, 0 replies; 20+ messages in thread
From: Drew Adams @ 2007-09-30 2:18 UTC (permalink / raw
To: tromey, help-gnu-emacs
> Alan> I didn't express myself very well. I think what I meant by
> Alan> "special purpose editor" was one that interprets the XML data
> Alan> structure and hides it from the user, much like Open Office does
> Alan> with ODF.
>
> This is sort of a diversion, but I've heard talk from time to time
> about writing such an editor as an Emacs mode. As an existing
> example, there's `enriched.el'. (Open etc/enriched.doc for an
> example, or look at it with find-file-literally to see the contents as
> they appear on disk.)
>
> A full ODF editor would be a major undertaking.
FWIW, and not terribly relevant to Emacs:
I didn't follow everything in this thread, but Adobe Framemaker does what
you describe: it is XML underneath (DTD or XML Schema), and users manipulate
things in WYSIWYG fashion. However, they can still see and manipulate the
document structure, without having to look at the XML code. It is in fact
quite a good XML round-trip editor for document-centric XML use cases.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: Emacs documentation.
[not found] ` <mailman.1488.1191103233.18990.help-gnu-emacs@gnu.org>
@ 2007-09-30 9:19 ` David Kastrup
0 siblings, 0 replies; 20+ messages in thread
From: David Kastrup @ 2007-09-30 9:19 UTC (permalink / raw
To: help-gnu-emacs
Alan Mackenzie <acm@muc.de> writes:
> On Sat, Sep 29, 2007 at 10:01:40PM +0200, David Kastrup wrote:
>>looked at Alan Mackenzie <acm@muc.de> writes:
>
>> >>Go ask around the OSS world what's being used for documentation.
>
>> > Why?
>
>> Because you'll find that any XML-based process would be rather
>> unusual (at least ouside of the Java world). Man-pages,
>> hand-written HTML, plain text files, Texinfo, LaTeX and other stuff
>> are more prevalent.
>
> That's what I would've thought. Given the existence of, in
> particular, TeX and LaTeX, I really don't understand what the point
> of Docbook is. (That's NOT a rhetorical comment.)
Well-formed Docbook-XML can be transformed in a number of ways without
further hassles. As an example, I have been able to transform the git
user manual into a valid Texinfo document just by calling some
converters.
That's impressive. In contrast, Texinfo is something that basically
happens to compile or not, given a particular version of texinfo.tex
and/or makeinfo.
You can also say "I don't like the look of this HTML/PDF/groff, let's
try a different converter/style", something which you can't do with
Texinfo.
If you take a look at, say,
<URL:http://www.kernel.org/pub/software/scm/git/docs/user-manual.html>,
you'll find that the look is quite more pleasant than the HTML
renditions of makeinfo. With Docbook/XML, playing with different end
formats and forms might be easier: the format can be translated
mechanically rather well _iff_ you are familiar with the toolchain and
how to program it.
> What has irritated me about David P.'s posts is he seems to assume
> that Docbook doesn't need justification - it is the Right Thing for
> any documentation application, and it is somehow not done to ask
> questions about it. I'm still hoping he'll come back with some
> answers.
Yes.
>> To be fair: people using Emacs _are_ generally using a special
>> purpose editor (in the form of a good major mode). Even LaTeX is
>> not uncommonly written with special purpose editors and modes.
>
> I didn't express myself very well. I think what I meant by "special
> purpose editor" was one that interprets the XML data structure and
> hides it from the user, much like Open Office does with ODF. I
> contrast this with an editor where you actually see and edit the raw
> XML file, possibly with the help of a good major mode. I suppose
> it's analogous to the difference between editing Elisp source files
> and hacking through the internal form created by the Lisp reader.
Hm, I think I draw the line differently. For me, Oxygen/XML is a
special-purpose XML editor, even though it will show the source text,
and Bluefish is a special-purpose HTML editor. Both can fold stuff
and validate it, but so can Emacs with nxml-mode. Kile
<URL:http://kile.sourceforge.net> is certainly a special-purpose LaTeX
editor even though it shows everything. Calling AUCTeX
<URL:http://www.gnu.org/software/auctex> non-special-purpose even
though it does dynamic folding of LaTeX structures, WYSIWYG rendition
in the source buffer
<URL:http://www.gnu.org/software/auctex/preview-latex.html>, source
special support and other stuff seems sort of disingenuous. In that
context, Emacs is not as much a general-purpose editor, but rather a
general-purpose editing platform on top of which special-purpose
editors are implemented in the form of major modes.
--
David Kastrup, Kriemhildstr. 15, 44793 Bochum
^ permalink raw reply [flat|nested] 20+ messages in thread
* emacs documentation
@ 2008-10-14 19:01 Sean Sieger
2008-10-14 19:15 ` Lennart Borgman (gmail)
2008-10-14 19:19 ` Drew Adams
0 siblings, 2 replies; 20+ messages in thread
From: Sean Sieger @ 2008-10-14 19:01 UTC (permalink / raw
To: help-gnu-emacs
I've been reading `An Introduction to Programming in Emacs Lisp' closely
and sometimes I come upon typos---or what look like typos, grammatical
or otherwise. To whom should I, or how should I report them? And more
generally, where is the information on how to contribute to
documentation?
Thank you.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: emacs documentation
2008-10-14 19:01 emacs documentation Sean Sieger
@ 2008-10-14 19:15 ` Lennart Borgman (gmail)
2008-10-14 19:25 ` Sean Sieger
2008-10-14 19:19 ` Drew Adams
1 sibling, 1 reply; 20+ messages in thread
From: Lennart Borgman (gmail) @ 2008-10-14 19:15 UTC (permalink / raw
To: Sean Sieger; +Cc: help-gnu-emacs
Sean Sieger wrote:
> I've been reading `An Introduction to Programming in Emacs Lisp' closely
> and sometimes I come upon typos---or what look like typos, grammatical
> or otherwise. To whom should I, or how should I report them? And more
> generally, where is the information on how to contribute to
> documentation?
http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00184.html
^ permalink raw reply [flat|nested] 20+ messages in thread
* RE: emacs documentation
2008-10-14 19:01 emacs documentation Sean Sieger
2008-10-14 19:15 ` Lennart Borgman (gmail)
@ 2008-10-14 19:19 ` Drew Adams
2008-10-14 23:07 ` Sean Sieger
1 sibling, 1 reply; 20+ messages in thread
From: Drew Adams @ 2008-10-14 19:19 UTC (permalink / raw
To: 'Sean Sieger', help-gnu-emacs
> I've been reading `An Introduction to Programming in Emacs
> Lisp' closely and sometimes I come upon typos---or what look like
> typos, grammatical or otherwise. To whom should I, or how should
> I report them? And more generally, where is the information on how
> to contribute to documentation?
`M-x report-emacs-bug'
See the Emacs manual, node Bugs.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: emacs documentation
2008-10-14 19:15 ` Lennart Borgman (gmail)
@ 2008-10-14 19:25 ` Sean Sieger
0 siblings, 0 replies; 20+ messages in thread
From: Sean Sieger @ 2008-10-14 19:25 UTC (permalink / raw
To: help-gnu-emacs
"Lennart Borgman (gmail)" <lennart.borgman@gmail.com> writes:
Sean Sieger wrote:
> I've been reading `An Introduction to Programming in Emacs Lisp' closely
> and sometimes I come upon typos---or what look like typos, grammatical
> or otherwise. To whom should I, or how should I report them? And more
> generally, where is the information on how to contribute to
> documentation?
http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00184.html
Right? This is the article that got me thinking about improving
GNU/Emacs and improving my use of it. Thanks, Lennart.
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: emacs documentation
2008-10-14 19:19 ` Drew Adams
@ 2008-10-14 23:07 ` Sean Sieger
0 siblings, 0 replies; 20+ messages in thread
From: Sean Sieger @ 2008-10-14 23:07 UTC (permalink / raw
To: help-gnu-emacs
"Drew Adams" <drew.adams@oracle.com> writes:
> I've been reading `An Introduction to Programming in Emacs
> Lisp' closely and sometimes I come upon typos---or what look like
> typos, grammatical or otherwise. To whom should I, or how should
> I report them? And more generally, where is the information on how
> to contribute to documentation?
`M-x report-emacs-bug'
See the Emacs manual, node Bugs.
Done.
Thank you, Drew.
^ permalink raw reply [flat|nested] 20+ messages in thread
end of thread, other threads:[~2008-10-14 23:07 UTC | newest]
Thread overview: 20+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2008-10-14 19:01 emacs documentation Sean Sieger
2008-10-14 19:15 ` Lennart Borgman (gmail)
2008-10-14 19:25 ` Sean Sieger
2008-10-14 19:19 ` Drew Adams
2008-10-14 23:07 ` Sean Sieger
-- strict thread matches above, loose matches on Subject: below --
2007-09-29 21:10 Emacs documentation martin rudalics
[not found] <mailman.1485.1191094713.18990.help-gnu-emacs@gnu.org>
2007-09-29 20:01 ` David Kastrup
2007-09-29 22:04 ` Alan Mackenzie
2007-09-29 22:05 ` Tom Tromey
2007-09-30 2:18 ` Drew Adams
[not found] ` <mailman.1488.1191103233.18990.help-gnu-emacs@gnu.org>
2007-09-30 9:19 ` David Kastrup
2007-09-23 9:53 Emacs documentation. Was My emacs was upgraded and I am a novice again Dave Pawson
2007-09-23 11:12 ` Bastien
2007-09-23 11:35 ` Dave Pawson
2007-09-29 15:46 ` Emacs documentation Alan Mackenzie
2007-09-29 15:47 ` Dave Pawson
2007-09-29 16:03 ` Peter Dyballa
2007-09-29 19:42 ` Alan Mackenzie
2007-09-29 16:33 ` Eli Zaretskii
2004-10-22 21:31 emacs documentation Tak Ota
2004-10-23 18:48 ` Richard Stallman
2004-10-23 19:25 ` Eli Zaretskii
2004-10-23 21:34 ` Eli Zaretskii
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.