Re: On being web-friendly and why info must die

[Achim Gratz]

Eli Zaretskii writes:
>> Would it be reasonable to pick one part of the Emacs manual -- 
>> doc/misc/org.texi, say -- and convert it to Org mode?  The idea is to see 
>> how 
>> well Org mode would work for representing all of the Emacs documentation, 
>> and 
>> perhaps we can convert it one manual at a time rather than trying to do it 
>> all 
>> at once.
>
> Good idea, IMO.  Any takers?

The idea is good enough that it has already been done and mentioned at
least three times in this very thread, with links to the result.  Since
nobody seems to have looked at it, here's the Introduction from that Org
manual in Org for your perusal.  If you look at it in Gnus it might even
use org-mode for display.

--8<---------------cut here---------------start------------->8---
* Introduction
  :PROPERTIES:
  :TITLE: Introduction
  :DESCRIPTION: Getting started
  :END:
{{{cindex(introduction)}}}

** Summary
   :PROPERTIES:
   :DESCRIPTION: Brief summary of what Org-mode does
   :END:
{{{cindex(summary)}}}

Org is a mode for keeping notes, maintaining TODO lists, and doing
project planning with a fast and effective plain-text system.

Org develops organizational tasks around NOTES files that contain
lists or information about projects as plain text. Org is implemented
on top of Outline mode, which makes it possible to keep the content of
large files well structured. Visibility cycling and structure editing
help to work with the tree. Tables are easily created with a built-in
table editor. Org supports TODO items, deadlines, timestamps, and
scheduling. It dynamically compiles entries into an agenda that
utilizes and smoothly integrates much of the Emacs calendar and diary.
Plain text URL-like links connect to websites, emails, Usenet
messages, BBDB entries, and any files related to the projects. For
printing and sharing notes, an Org file can be exported as a
structured ASCII file, as HTML, or as an iCalendar file.[fn:1]  It can
also serve as a publishing tool for a set of linked web pages.

As a project planning environment, Org works by adding metadata to
outline nodes. Based on this data, specific entries can be extracted
in queries and create dynamic /agenda views/.

Org mode contains the Org Babel environment which allows you to work
with embedded source code blocks in a file, to facilitate code
evaluation, documentation, and literate programming techniques.

Org's automatic, context-sensitive table editor with spreadsheet
capabilities can be integrated into any major mode by activating the
minor Orgtbl mode. Using a translation step, it can be used to
maintain tables in arbitrary file types, for example in LaTeX. The
structure editing and list creation capabilities can be used outside
Org with the minor Orgstruct mode.

Org keeps simple things simple. When first fired up, it should feel
like a straightforward, easy to use outliner. Complexity is not
imposed, but a large amount of functionality is available when you
need it. Org is a toolbox and can be used in different ways and for
different ends, for example:

  - an outline extension with visibility cycling and structure editing
  - an ASCII system and table editor for taking structured notes
  - a TODO list editor
  - a full agenda and planner with deadlines and work scheduling
    {{{pindex(GTD\\\, Getting Things Done)}}}
  - an environment in which to implement David Allen's GTD system
  - a simple hypertext system, with HTML and LaTeX export
  - a publishing tool to create a set of interlinked web pages
  - an environment for literate programming

{{{cindex(FAQ)}}} 

There is a [[http://orgmode.org][website for Org]] that provides links to the 
newest version
of Org, as well as additional information, frequently asked questions
(FAQ), links to tutorials, etc.

{{{cindex(print edition)}}} 

Version 7.3 of this manual is available as a 
[[http://www.network-theory.co.uk/org/manual/][paperback book from
Network Theory Ltd.]]

{{{page}}}

** Installation
   :PROPERTIES:
   :DESCRIPTION: Installing Org
   :END:

{{{cindex(installation)}}}
{{{cindex(XEmacs)}}}

Org is part of recent distributions of GNU Emacs, so you normally don't need
to install it.  If, for one reason or another, you want to install a
different version of Org, there are three ways to do it:

- use the Emacs package system;
- download Org as an archive; or
- use the Org git repository.

We *strongly recommend* that you use only one of these installation
methods.

*** Install from the Emacs package system

Recent Emacs distributions include a packaging system which lets you
install Elisp libraries.  You can install the development version of
Org with {{{kbd(M-x package-install RET org)}}}.  You need to do this
in a session where no {{{file(.org)}}} file has been visited.  Then,
to make sure your Org configuration is taken into account, initialize
the package system with ~(package-initialize)~ in your
{{{file(.emacs)}}} before setting any Org option.  If you want to use
Org's package repository, check out the [[http://orgmode.org/elpa.html][Org 
ELPA page]].

*** Download Org as an archive

You can download the latest Org release from the [[http://orgmode.org/][Org 
mode website]],
typically to a location under your home directory.  Optionally, you
can compile the files and/or install them in your system.  Run ~make
help~ to list compilation and installation options.

It is possible to use the latest Org release from the download
location without installing it in your system files.  In this case,
make sure you set the load-path correctly in {{{file(.emacs)}}}:

#+begin_example
     (add-to-list 'load-path "~/path/to/orgdir/lisp")
#+end_example

The downloaded archive contains contributed libraries that are not
included in Emacs.  If you want to use them, add the {{{file(contrib)}}}
directory to your load-path:

#+begin_example
     (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
#+end_example

*** Use the Org git repository

You can clone the development version of the Org git repository,
typically to a location under your home directory.  The example in
this section assumes this location is ~src/~ in your home directory:

#+begin_example
   $ cd ~/src/
   $ git clone git://orgmode.org/org-mode.git
   $ cd org-mode
#+end_example

In most cases where you have permission to write to system locations,
you will probably want to install Org with the Emacs system files.
This is a system-specific operation that is guided by a file,
{{{file(local.mk)}}}, which you must ensure is configured properly.
First, generate a {{{file(local.mk)}}} template with the command ~make
local.mk~.  Edit {{{file(local.mk)}}} following the instructions in
the file, and save it.[fn:185] Check to be sure the build system sees
your changes by running ~make config~.  If all is well, run ~make
install~ to build Org and install it.  The command ~make help~
provides a list of options for the build system.

If you would like to run Org from the clone location, instead of
installing it with the Emacs system files, you can simply run ~make
autoloads~ and set the load-path in your {{{file(.emacs)}}}.
Using the example location, add this to {{{file(.emacs)}}}:

#+begin_example
     (add-to-list 'load-path "~/src/org-mode/lisp")
#+end_example

If your installation has special requirements, please refer to the
detailed description of the capable build system at the 
[[http://orgmode.org/worg/dev/org-build-system.html][Org Build
System page]].

** Activation
   :PROPERTIES:
   :DESCRIPTION: How to activate Org-mode for certain buffers
   :END:
{{{cindex(activation)}}}
{{{cindex(autoload)}}}
{{{cindex(ELPA)}}}
{{{cindex(global key bindings)}}}
{{{cindex(key bindings\\\, global)}}}
{{{findex(org-agenda)}}}
{{{findex(org-capture)}}}
{{{findex(org-store-link)}}}
{{{findex(org-iswitchb)}}}

Since Emacs 22.2, files with the {{{file(.org)}}} extension use Org mode by
default.  If you are using an earlier version of Emacs, add this line to your
{{{file(.emacs)}}} file:

#+header: :exports code
#+header: :eval no
#+begin_src emacs-lisp
(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
#+end_src

Org mode buffers need font-lock to be turned on: this is the default in
Emacs.[fn:5]

There are compatibility issues between Org mode and some other Elisp
packages, please take the time to check the list (see [[Conflicts]]).

The four Org commands {{{command(org-store-link)}}},
{{{command(org-capture)}}}, {{{command(org-agenda)}}}, and
{{{command(org-iswitchb)}}} should be accessible through global keys
(i.e., anywhere in Emacs, not just in Org buffers).  Here are
suggested bindings for these keys, please modify the keys to your own
liking.

#+header: :exports code
#+header: :eval no
#+begin_src emacs-lisp
(global-set-key "\C-cl" 'org-store-link)
(global-set-key "\C-cc" 'org-capture)
(global-set-key "\C-ca" 'org-agenda)
(global-set-key "\C-cb" 'org-iswitchb)
#+end_src

{{{cindex(Org mode\\\, turning on)}}} 
With this setup, all files with extension {{{samp(.org)}}} will be put
into Org mode.  As an alternative, make the first line of a file look
like this:

#+begin_example
   MY PROJECTS    -*- mode: org; -*-
#+end_example

{{{vindex(org-insert-mode-line-in-empty-file)}}} 
{{{noindent}}}
which will select Org mode for this buffer no matter what the file's
name is. See also the variable
~org-insert-mode-line-in-empty-file~.

Many commands in Org work on the region if the region is /active/. To
make use of this, you need to have ~transient-mark-mode~
(~zmacs-regions~ in XEmacs) turned on. In Emacs 23 this is the
default, in Emacs 22 you need to do this yourself with

#+header: :exports code
#+header: :eval no
#+begin_src emacs-lisp
(transient-mark-mode 1)
#+end_src

{{{noindent}}} If you do not like ~transient-mark-mode~, you can
create an active region by using the mouse to select a region, or
pressing {{{kbdkey(C-,SPC)}}} twice before moving the cursor.

** Feedback
   :PROPERTIES:
   :DESCRIPTION: Bug reports, ideas, patches, etc.
   :END:
{{{cindex(feedback)}}}
{{{cindex(bug reports)}}}
{{{cindex(maintainer)}}}
{{{cindex(author)}}}

If you find problems with Org, or if you have questions, remarks, or
ideas about it, please mail to the Org mailing list
[[mailto:address@hidden If you are not a member of
the mailing list, your mail will be passed to the list after a
moderator has approved it.[fn:6]

For bug reports, please first try to reproduce the bug with the latest
version of Org available---if you are running an outdated version, it
is quite possible that the bug has been fixed already. If the bug
persists, prepare a report and provide as much information as
possible, including the version information of Emacs ({{{kbdspckey(M-x
emacs-version,RET)}}}) and Org ({{{kbdspckey(M-x org-version,RET)}}}),
as well as the Org related setup in {{{file(.emacs)}}}. The easiest
way to do this is to use the command {{{kbd(M-x
org-submit-bug-report)}}}, which will put all this information into an
Emacs mail buffer so that you only need to add your description. If
you are not sending the Email from within Emacs, please copy and paste
the content into your Email program.

Sometimes you might face a problem due to an error in your Emacs or
Org mode setup.  Before reporting a bug, it is very helpful to start
Emacs with minimal customizations and reproduce the problem.  Doing so
often helps you determine if the problem is with your customization or
with Org mode itself.  You can start a typical minimal session with a
command like the example below.

#+begin_src sh :exports code
$ emacs -Q -l /path/to/minimal-org.el
#+end_src

However if you are using Org mode distributed with Emacs, a minimal
setup is not necessary. In that case it is sufficient to start Emacs
as ~emacs -Q~. The ~minimal-org.el~ setup
file can have contents as shown below.

#+header: :exports code
#+header: :eval no
#+begin_src emacs-lisp
;;; Minimal setup to load latest `org-mode'

;; activate debugging
(setq debug-on-error t
      debug-on-signal nil
      debug-on-quit nil)

;; add latest org-mode to load path
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
#+end_src

If an error occurs, a backtrace can be very useful (see [[How to
create a useful backtrace]]). Often a small example file helps, along
with clear information about:

  1. What exactly did you do?
  2. What did you expect to happen?
  3. What happened instead?

{{{noindent}}} Thank you for helping to improve this program.

** How to create a useful backtrace
   :PROPERTIES:
   :DESCRIPTION: The best way to report an error
   :END:

{{{cindex(backtrace of an error)}}}

If working with Org produces an error with a message you don't
understand, you may have hit a bug.  The best way to report this is by
providing, in addition to what was mentioned above, a /backtrace/.
This is information from the built-in debugger about where and how the
error occurred.  Here is how to produce a useful backtrace:

  1. Reload uncompiled versions of all Org mode Lisp files. The
     backtrace contains much more information if it is produced with
     uncompiled code. To do this, use 
     {{{kbdspckey(C-u M-x org-reload,RET)}}} or select 
     ~Org -> Refresh/Reload -> Reload Org uncompiled~ from the menu.

  2. Go to the ~Options~ menu and select ~Enter Debugger on Error~
     (XEmacs has this option in the ~Troubleshooting~ sub-menu).

  3. Do whatever you have to do to hit the error. Don't forget to
     document the steps you take.

  4. When you hit the error, a {{{file(*Backtrace*)}}} buffer will
     appear on the screen.  Save this buffer to a file (for example
     using {{{kbd(C-x C-w)}}}) and attach it to your bug report.

** Conventions
   :PROPERTIES:
   :DESCRIPTION: Typesetting conventions in the manual
   :END:

Conventions for typesetting keywords, keybindings, and commands in
this manual are described.

*** Three types of keywords
    :PROPERTIES:
    :DESCRIPTION: TODO, tags, and properties
    :END:

Org mainly uses three types of keywords: TODO keywords, tags and property
names.  In this manual we use the following conventions:

  - TODO, WAITING :: TODO keywords are written with all capitals, even if they
    are user-defined.
  - boss, ARCHIVE :: User-defined tags are written in lowercase; built-in
               tags with special meaning are written with all capitals.
  - Release, PRIORITY :: User-defined properties are capitalized; built-in
                properties with special meaning are written with all capitals.

Moreover, Org uses /option keywords/ (like ~#+TITLE~ to set the title)
and /environment keywords/ (like ~#+BEGIN_HTML~ to start a ~HTML~
environment). They are written in uppercase in the manual to enhance
its readability, but you can use lowercase in your Org files.[fn:7]

*** Keybindings and commands
    :PROPERTIES:
    :DESCRIPTION: Bind useful commands to keys
    :END:

{{{kindex(C-c a)}}}
{{{findex(org-agenda)}}}
{{{kindex(C-c c)}}}
{{{findex(org-capture)}}}

The manual suggests two global keybindings: {{{kbd(C-c a)}}} for
~org-agenda~ and {{{kbd(C-c c)}}} for ~org-capture~. These are only
suggestions, but the rest of the manual assumes that you are using
these keybindings.

Also, the manual lists both the keys and the corresponding commands
for accessing a functionality. Org mode often uses the same key for
different functions, depending on context. The command that is bound
to such keys has a generic name, like ~org-metaright~.  In the manual
we will, wherever possible, give the function that is internally
called by the generic command. For example, in the chapter on document
structure, {{{kbdkey(M-,right)}}} will be listed to call
~org-do-demote~, while in the chapter on tables, it will be listed to
call ~org-table-move-column-right~. 

#+comment: If you prefer, you can compile the manual without the command names 
by unsetting the flag ~cmdnames~ in {{{file(org.texi)}}}.

--8<---------------cut here---------------end--------------->8---


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

Factory and User Sound Singles for Waldorf Q+, Q and microQ:
http://Synth.Stromeko.net/Downloads.html#WaldorfSounds