view admin/notes/documentation @ 99139:8fa7ef477c04

2008-10-26 Carsten Dominik <[e-mail]> * org-agenda.el (org-format-agenda-item) (org-agenda-filter-make-matcher): Make sure tags are stored and compared donwcased. 2008-10-26 Carsten Dominik <[e-mail]> * org.el (org-insert-todo-heading): Fix bug with force-heading argument. 2008-10-26 Carsten Dominik <[e-mail]> * org-exp.el (org-export-as-ascii): Handle the case that we are bulishing from an indirect buffer. * org-table.el (org-table-copy-down): Fix bug with time stamp increment. * org-mouse.el (org-mouse-features): New option. (org-mode-hook): Turn on features depending on `org-mouse-features'. * org.el (org-insert-heading-respect-content): Force heading creation. (org-insert-heading): keep the folding state of the heading before the inserted one. 2008-10-26 Carsten Dominik <[e-mail]> * org-archive.el (org-archive-to-archive-sibling): Handle top level headlines better. 2008-10-26 Bastien Guerry <[e-mail]> * org-export-latex.el (org-export-latex-classes): Added \usepackage{graphicx} to the default list of packages. 2008-10-26 Carsten Dominik <[e-mail]> * org-agenda.el (org-agenda-filter): Renamed from `org-agenda-filter-tags'. 2008-10-26 Carsten Dominik <[e-mail]> * org.el (org-entry-properties): Add CATEGORY property, iven if it is not defined as a property in this entry. (org-add-log-note): Mask prefix argument when immediately storing the note. * org-agenda.el (org-agenda-filter-effort-default-operator): New option. 2008-10-26 James TD Smith <[e-mail]> * org.el (org-add-log-setup): Bugfix; code to find insertion point after drawers was skipping ahead one line too many, so notes were inserted after the first note instead of before it. 2008-10-26 Carsten Dominik <[e-mail]> * org-agenda.el (org-agenda-filter-tags,org-agenda-filter-form): New variables. (org-prepare-agenda): Reset the filter tags. (org-agenda-filter-by-tag, org-agenda-filter-by-tag-show-all): Show filter tags in mode line. * org-table.el (orgtbl-to-html): Bind `html-table-tag' for the formatter. * org-export-latex.el (org-latex-entities-regexp): New constant. (org-export-as-pdf): Use two calls to `shell-command'. 2008-10-26 Carsten Dominik <[e-mail]> * org-export-latex.el (org-export-latex-treat-sub-super-char): Honor the {} value of the subsuperscript setting. Make sure that longer subsuperscripts are typeset in a roman font. * org.el (org-clock-update-time-maybe): Compute negative clock intervals correctly. 2008-10-26 Carsten Dominik <[e-mail]> * org.el (org-add-log-setup): Respect `org-log-state-notes-insert-after-drawers'. (org-log-state-notes-insert-after-drawers): New option. (org-todo-trigger-tag-changes): New function. (org-todo): Call `org-todo-trigger-tag-changes'. 2008-10-26 James TD Smith <[e-mail]> * org.el (org-add-log-setup): Only skip drawers if the are immediately after the scheduling keywords. * org-clock.el (org-clock-in-switch-to-state): Allow this to be a function (org-clock-in): If `org-clock-in-switch-to-state' is a function, call it with the current todo state to get the state to switch to when clocking in. (org-clock-in): Use org-indent-line-function to indent clock lines. (org-clock-find-position): Fix indentation of empty clock drawers. 2008-10-26 Carsten Dominik <[e-mail]> * org-publish.el (org-publish-org-to): Handle case when org-export-to-pdf does return a file name, not a buffer. (org-publish-org-to-pdf): New function. * org-export-latex.el (org-export-as-pdf) (org-export-as-pdf-and-open): New commands. * org-table.el (org-table-eval-formula): Avoid parsing Calc's HMS forms as ranges. * org-export-latex.el (org-export-latex-lists): Ignore lists-like things in protexted regions. 2008-10-26 Carsten Dominik <[e-mail]> * org-export-latex.el (org-export-latex-preprocess): Improve quoting of LaTeX environments.

-*- outline -*-

Some documentation tips culled from emacs-devel postings.


** Manual indices

http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00400.html

For example, this text:

    @vindex x-gtk-show-hidden-files
    @vindex x-gtk-file-dialog-help-text
      When Emacs is compiled with GTK+ support, it uses the GTK+ ``file
    chooser'' dialog.  Emacs adds an additional toggle button to this
    dialog, which you can use to enable or disable the display of hidden
    files (files starting with a dot) in that dialog.  If you want this
    toggle to be activated by default, change the variable
    @code{x-gtk-show-hidden-files} to @code{t}.  In addition, Emacs adds
    help text to the GTK+ file chooser dialog; to disable this help text,
    change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}.

has index entries for the variables it describes, which is good, but
what if a user looks for this information without knowing the names of
these variables?  For those, I added these two concept index entries:

    @cindex hidden files, in GTK+ file chooser
    @cindex help text, in GTK+ file chooser

Thus, if a user types "i hidden files TAB" in Info, she will see the
first entry, and so if she types "i file chooser RET".  See why it is
better?

The way to come up with useful index entries is to put yourself in the
shoes of someone who looks for the information, and think about words
and phrases you'd use to find it.

One other rule for good indexing is not to have several index entries
that begin with the same substring and point to the same page or
screenful (i.e. to places that are close to one another).  Here's a
fictitious example of such redundant entries:

  @cindex foobar, how to use
  @cindex foobar rules

  Either leave only one of these, e.g. just "@cindex foobar", or
combine them into a single entry, e.g.:

  @cindex foobar, rules and usage


** Point is a proper name

http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00414.html

In Emacs tradition, we treat "point" as a proper name when it refers
to the current editing location. It should not have an article.

Thus, it is incorrect to write, "The point does not move". It should
be, "Point does not move".

If you see "the point" anywhere in Emacs documentation or comments,
referring to point, please fix it.


** Don't use passive verbs

http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00414.html

Documentation is clearer if it avoids the passive voice whenever
possible.  For example, rather than saying "Point does not move", say
"This does not move point".  If you come across passive verbs in Emacs
documentation or comments, please see if it is possible to make the
text shorter and clearer using the active voice.  Usually that does
make an improvement.  The explicit subject required by the active voice
often provides important information which makes the text clearer, too.