From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Achim Gratz Newsgroups: gmane.emacs.devel Subject: Re: On being web-friendly and why info must die Date: Thu, 11 Dec 2014 19:33:33 +0100 Organization: Linux Private Site Message-ID: <87iohiujcy.fsf@Gertrud.fritz.box> References: <20141205123549.GA29331@thyrsus.com> <83k325195l.fsf@gnu.org> <5482D94B.2070102@cs.ucla.edu> <5484FF31.5010808@cs.ucla.edu> <5485FC59.5030700@cs.ucla.edu> <87388p6glt.fsf@engster.org> <871to9lw6g.fsf@fencepost.gnu.org> <5486A704.6090305@cs.ucla.edu> <87k321jj4e.fsf@fencepost.gnu.org> <54876F7F.9000607@cs.ucla.edu> <87y4qfj2u9.fsf@fencepost.gnu.org> <54889A57.5060905@cs.ucla.edu> <87vbljb9f4.fsf@wanadoo.es> <54889F6D.6060408@cs.ucla.edu> <87r3w7b83a.fsf@wanadoo.es> <5488C710.3000209@cs.ucla.edu> <871to7ayv9.fsf@wanadoo.es> <5488DC0C.2070402@cs.ucla.edu> <837fxyt78a.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1418322860 6722 80.91.229.3 (11 Dec 2014 18:34:20 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 11 Dec 2014 18:34:20 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Thu Dec 11 19:34:15 2014 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Xz8Z1-0002HX-0q for ged-emacs-devel@m.gmane.org; Thu, 11 Dec 2014 19:34:11 +0100 Original-Received: from localhost ([::1]:53090 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xz8Z0-0001zk-GW for ged-emacs-devel@m.gmane.org; Thu, 11 Dec 2014 13:34:10 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58400) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xz8Yf-0001yZ-UO for emacs-devel@gnu.org; Thu, 11 Dec 2014 13:33:55 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Xz8Ya-0000r7-Oo for emacs-devel@gnu.org; Thu, 11 Dec 2014 13:33:49 -0500 Original-Received: from plane.gmane.org ([80.91.229.3]:58633) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xz8Ya-0000r3-Cm for emacs-devel@gnu.org; Thu, 11 Dec 2014 13:33:44 -0500 Original-Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1Xz8YY-0001lT-FX for emacs-devel@gnu.org; Thu, 11 Dec 2014 19:33:42 +0100 Original-Received: from p54b7ffb3.dip0.t-ipconnect.de ([84.183.255.179]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 11 Dec 2014 19:33:42 +0100 Original-Received: from Stromeko by p54b7ffb3.dip0.t-ipconnect.de with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 11 Dec 2014 19:33:42 +0100 X-Injected-Via-Gmane: http://gmane.org/ Original-Lines: 418 Original-X-Complaints-To: usenet@ger.gmane.org X-Gmane-NNTP-Posting-Host: p54b7ffb3.dip0.t-ipconnect.de User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux) Cancel-Lock: sha1:K6iU6GhXcXvkd2xLm9q/a1tRF4k= X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 80.91.229.3 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:179813 Archived-At: 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:emacs-orgmode@gnu.org]]. 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