Re: Website revamp?

[Maxim Nikulin <manikulin@gmail.com>]

04.08.2020 22:53, TEC wrote:
> 
> I love the idea of a demo org file! If anyone would like to help out with creating one by sending in contenders / snippets that would be brilliant!
> 
> Even better - having two or three different demo files based on the use case of
> the new user - e.g. programmer, author, organisation - or something like that.

Actually I still believe that such files already exist.
Note taking demo/intro, in my opinion,
should be roughly as following:

#+STARTUP: overview
#+TITLE: Emacs org-mode demo: header navigation
#+AUTHOR: A relatively new org-mode user

#+begin_abstract
This is an example of =.org= document demonstrating
features that make Emacs with Org-mode a convenient
application for keeping notes.
Tree-like structure allows to show some section
and fold into header line currently unimportant parts.
Rich set of commands helps to manage sections,
jump over headers, search for specific content.
Tags and internal links set relations for notes
stored in different parts of the tree.
#+end_abstract

#+begin_comment
Use =C-c C-n= (it is Emacs notation equivalent to =[Ctrl+c][Ctrl+n]=)
to jump to the first section header.
Having cursor in a header line, try to press =TAB= several times
to reveal section content and to collapse subtree again.
#+end_comment

* Sections

You could read and write org files in any text editor,
but to discover org-mode real power, open this file in Emacs[fn:1].

A line started with stars is a section header.
Org document is a tree of such sections.
Single =*= adds a top level section.

Reading this file for the first time, likely it is better
to ignore links to the manual.

Manual: [[https://orgmode.org/manual/Headlines.html][Headlines]]@@org:, [[info:org#Headlines][internal info]]@@.

[fn:1] You might be reading a file exported to PDF or HTML.
To get notion of org-mode markup, compare it to the content
of the original =.org= file.

# Certainly you have guessed that previous paragraph
# adds a footnote.
# This is a comment, a part of text not intended for export.

** Headers tree and visibility

More stars means deeper into the notes tree.

You could manage which parts of the document are currently
important for you. open the related sections
and close everything else.

- =TAB= :: when cursor is in the section header, this key
   - shows section content,
   - then shows whole subtree,
   - then hides subtree again,
   - then the cycle repeats.
- =S-TAB= (=[Shift+Tab]=) :: change subtree visibility
     for the whole document

Above =...= marks verbatim inline text, =- term :: definition=
are the items of a definition list. Just dashes
without colons is an unordered list, certainly lists
could be nested.

There are =#+begin_...#+end_...= blocks e.g. in the very beginning
of the document. They could be folded or opened with =TAB= key as well
while cursor is on the =#+begin_...= line.
On the other hand blocks do not obey commands changing visibility
of section content.

Manual: [[https://orgmode.org/manual/Visibility-Cycling.html][Visibility Cycling]]@@org:, [[info:org#Visibility Cycling][internal docs]]@@;
[[https://orgmode.org/manual/Plain-Lists.html][Plain Lists]]@@org:, [[info:org#Plain Lists][internal docs]]@@.

** Navigation

Moving cursor with arrows is unnecessary slow,
=[PgDown]= could be too coarse when most of the sections
are closed. There is a number of commands
that move cursor to a particular header.

- =C-c C-u= :: jump to upper level
- =C-c C-n= :: go to the next header
- =C-c C-p= :: previous header
- =C-c C-f= :: jump forward to the header having the same level
- =C-c C-b= :: backward to the header at the same level

=C-l= Emacs command moves line with cursor to the center, top,
then to the bottom of the screen and could make header context
more clear.

Do not be afraid by a lot of new keystrokes.
The same action you could find in the Org menu.
The lists are added just to populate content
of this file with something less boring than
"Header one", "Header two", and "Lorem ipsum..."

Manual: [[https://orgmode.org/manual/Motion.html][Motion]]@@org:, [[info:org#Motion][internal docs]]@@.

*** How to hide leading stars and to add indent                        :code:
    :PROPERTIES:
    :CUSTOM_ID: startup_indent
    :END:

For those who decided to try navigation commands,
this node makes it apparent next vs. forward commands difference.

I was tempting to add
: #+STARTUP: indent
as the first line of this document. I found convenient to have
indent increasing with tree depth. Finally I decided
that it is more important for a demo file to have all stars
marking header file visible.

Colon as a first non-space symbols is intended for short
preformatted (verbatim) blocks.

Manual: [[https://orgmode.org/manual/Org-Indent-Mode.html][Org Indent Mode]]@@org:, [[info:org#Clean%20View][internal docs]]@@.

** Creation of new headers

Nobody forbids to type stars directly. However
=C-RET= and =M-RET= (=[Esc] [Enter]= or =[Alt+Enter]= for the latter)
are more convenient. Their actions are not strictly similar,
e.g. =M-RET= could create a new list item, not a new header.

Use =C-/= for undo, if you have tried any of the command.

Certainly there are a number of commands to reorder
headers, to move them e.g. deeper, etc. You will find
them in the manual.

Manual: [[https://orgmode.org/manual/Structure-Editing.html][Structure Editing]]@@org:, [[info:org#Structure Editing][internal docs]]@@.

** Tags
   :PROPERTIES:
   :CUSTOM_ID: tags
   :END:

Certainly real life notes could not be structured
as a simple tree. Often it is difficult to create unambiguous
tree and decide which branch new remark belongs to.

Several tags could be assigned to a headline, notice ":code:"
keyword added to some sections.
You could type them directly or use =C-c C-q= command.

To search notes having specific tags use =C-c / m=. The result is
so called sparse tree. Command =C-c C-r= is intended to reveal
sibling headers in such view. In this document sections
containing =#+begin_example= and =#+begin_src= blocks are marked
with the =code= tag expecting that some readers would eager
to try it immediately.

Manual: [[https://orgmode.org/manual/Tags.html][Tags]]@@org:, [[info:org#Tags][internal docs]]@@.

** Comments

There are several ways to mark parts of document as comments. Single line
could be prepended by hash sign,
# This is a comment
use a comment block,
#+begin_comment
Multi
line
comment
#+end_comment
or whole subtree as below[fn:2].

There is a little reason to use comments in private notes
but if you are preparing a paper, a blog post, or materials
for students, comments allows to add remarks valuable for you
but unnecessary in a shared document. Tags add another way
to control contents of an exported document.

Manual: [[https://orgmode.org/manual/Comment-Lines.html][Comment Lines]]@@org:, [[info:org#Comment Lines][internal docs]]@@.

[fn:2] In PDF or HTML file this note should especially
puzzling since comments are intentionally stripped.

*** COMMENT Do not export this subtree

Details on tags and export are redundant in this demo file.

**** And deeper headers

Children of commented out section would not be exported as well.

* Links

** Internal links                                                      :code:
  :PROPERTIES:
  :CUSTOM_ID: internal_link
  :END:

You already know that it is possible to create a group of notes
assigning tags to headers.

It is useful to cross-link notes with internal links.
Such directed graph has no restriction to be a tree.
Links makes relations explicit, for example a link could remind you
that you realized some fact while you were reading a particular article.

[[#link_back][Try to follow this link]], press =C-c C-o= to activate it. To move cursor
to the next or to the previous link there are speed keys =C-c C-x C-n=
and =C-c C-x C-p=.

The link above is added as
#+begin_example
[[#link_back][Try to follow this link]]
#+end_example
first part is link target, second one is description.
The latter could be omitted. For private notes not intended
for export I found it convenient to see link target.
In org files hash sign causes lookup for a heading
having such =CUSTOM_ID= property. Alternative if
you consider header text stable enough, you can use
it as link target prepending it with star
[[*Tags][*Tags]].

It is possible to switch to literal links instead
of descriptive links e.g. through menu.

Literal blocks could be added with =#+begin_example= as above.
Another possibility are blocks as =#+begin_src python=.
Let's remind that in the [[#startup_indent]] section,
leading =:= was used for a similar purpose.

Manual: [[https://orgmode.org/manual/Internal-Links.html][Internal Links]]@@org:, [[info:org#Internal Links][internal docs]]@@;
[[https://orgmode.org/manual/Handling-Links.html][Handling Links]]@@org:, [[info:org#Handling Links][internal docs]]@@.

** Other types of links
   :PROPERTIES:
   :CUSTOM_ID: other_links
   :END:

Of course, link target could be e.g. [[https://orgmode.org]]

=C-c C-l= shortcut is intended to insert links.
Find more info @@org: in Emacs internal info documentation [[info:org#Link%20format][info:org#Link format]] or@@ in
online version of the manual: [[https://orgmode.org/manual/Link-Format.html#Link-Format][Link format]].
@@org:There is also internal reference for the function
bound to the shortcut [[help:org-insert-link]]@@

Magic with =@@= is necessary for better [[*Export][export]].
Could you guess the target of the link in the previous sentence?
Move cursor to it and try =C-h .=.

Manual: [[https://orgmode.org/manual/External-Links.html][External Links]]@@org:, [[info:org#External Links][internal docs]]@@.

** Notice mostly for Debian and Ubuntu users                           :code:

Emacs docs are shipped in a separate package.
Depending on distribution version, try something like

#+begin_src bash :results none
  apt install emacs-common-non-dfsg
#+end_src

#+begin_src bash :results none
  apt install emacs25-common-non-dfsg
#+end_src

By the way, it is possible to run command directly
from Emacs. Move cursor inside a src block
and try =C-c C-c=. Unless org-mode is configured already,
command likely failed. You could add "shell" language
through customize interface (see "Org" menu).
Alternatively execute with =C-c C-c= the following block
than try commands above.

#+begin_src emacs-lisp :results none
  (add-to-list 'org-babel-load-languages (cons (intern "shell") t))
  (org-babel-do-load-languages
   'org-babel-load-languages org-babel-load-languages)
#+end_src

There is no ob-shell in org 8.2.10 bundled with emacs-25.2 (Ubuntu-18.04 bionic).
By the way, it is one more reason to update org-mode to a newer version.

Are you afraid of lisp? Do not worry, its syntax
is much more compact in comparison to the most
of widely spread languages. Emacs is extremely flexible
and if you start using org-mode, you will find
yourself adding custom lisp functions to your emacs =init.el=
soon.

So org files could contain executable code.
Aren't you afraid of macro viruses yet?
Do not open org files obtained from non-trusted sources
with Emacs.

** How to copy target for an internal link

=M-x org-store-link= command saves link to current
section for further inserting it with =C-c C-l=.

Manual suggest to create a global shortcut for this command,
see Activation section in @@org:[[info:org#Activation][internal manual]] or @@
[[https://orgmode.org/manual/Activation.html][online docs]]

* Formatting

*Bold*, /italic/, _underlined_, +strke-trough+ strike-through,
=verbatim= fixed width and ~code~ text could be used.

Manual: [[https://orgmode.org/manual/Emphasis-and-Monospace.html][Emphasis and Monospace]]@@org:, [[info:org#Emphasis and monospace][internal docs]]@@.

* Adding timestamps

Scheduling meetings, tasks, events, working with
agenda view, exporting to iCal files should be
subject of another demo file.

However I add timestamps to notes with =C-u C-u C-c !=
[2020-08-11 Tue 15:10]. Just =C-c != prompts for date
and does not adds time. You may find =git blame=
enough for similar purpose.

Manual: [[https://orgmode.org/manual/Dates-and-Times.html][Dates and Times]]@@org:, [[info:org#Dates and Times][internal docs]]@@.

* Search and filter

Certainly you could use ordinary Emacs incremental search

|-------------+------------------------------------------------------|
| =C-s=       | forward, press it again to go to the next occurrence |
| =C-r=       | backward; when forward search is already active,     |
|             | change its direction (=C-s= acts in a similar way)   |
| =RET=       | accept the found position                            |
| =C-g=       | abandon search (at first drop non-matched part)      |
| =C-u C-SPC= | jump back from the found position                    |
|-------------+------------------------------------------------------|

Do not mess it up, in a browser =[Ctrl+g]= repeats
the search, in Emacs =C-g= cancels it.

If you are overwhelmed by the new portion of keystrokes,
you may like to know that at least you do not have to remember
separate shortcuts for undo and redo. =C-/= does both
things since redo is just undo of undo.
Any cursor movement or =C-g= revert direction from undo
to redo. I am lying a bit. There are more keystrokes
for undo and redo but they acts in a same way: =C-_=, =C-x u=,
so just pick the one you like more.

There was a table above. Some wiki engines use similar markup.
It is still more convenient to edit tables in a emacs =.org=
file and copy result to browser. =TAB=, =RET=, =C-c C-c=, and
some other shortcuts causes realign of the table, so it looks neat.
A couple of characters =|-= is enough to get whole horizontal line.
If you need a table for a @@latex:\\@@LaTeX file prepared without
using of org-mode, it could still be convenient to export
particular section of org file to @@latex:\\@@LaTeX. Org markup
for tables is more readable.

# FIXME spurious line breaks before LaTeX

Manual: [[https://orgmode.org/manual/Tables.html][Tables]]@@org:, [[info:org#Tables][internal docs]]@@.@@org: [[info:emacs#Incremental Search][Incremental Search (Emacs)]].@@

** Jump back after following a link
   :PROPERTIES:
   :CUSTOM_ID: link_back
   :END:

Maybe you found yourself here trying to follow a link.
Notice =:PROPERTIES:= block above. It is folded tighter
than header but you still can open it placing cursor to it
and pressing =TAB=. It contains anchor defined as =CUSTOM_ID=
property.

To return to the place where you were before activating a link,
press =C-c &=. Adding a link is described in [[#internal_link]],
that could be followed with =C-c C-o=.

There is a shortcut =C-c C-x p= to add a drawer for properties.
Create =CUSTOM_ID= property (=TAB= completion works for property names).

** Filter headers using =org-occur=

- =C-c C-/ r= or =M-x org-occur= :: show only sections containing
     the found pattern@@org: ([[help:org-occur][~org-occur~ help]])@@.

As an short exercise try to filter notes containing word "link".
Let's remind global visibility command =S-TAB=.

Manual: [[https://orgmode.org/manual/Sparse-Trees.html][Sparse Trees]]@@org:, [[info:org#Sparse Trees][internal docs]]@@.

** Jump to particular header

Are you remember how to add tags to header?
Let's look at the section once more. Tab completion
works, so you have not type full headers.
Do not forget =C-c &= to return back.

=C-u C-c C-j sec TAB tag TAB RET=

Manual: [[https://orgmode.org/manual/Motion.html][Motion]]@@org:, [[info:org#Motion][internal docs]]@@.

* Export

If you have @@latex:\\@@LaTeX installed, you could make a PDF
file from this document using =C-c C-e l o=.
Almost certainly you already have some browser installed
so export to HTML with =C-c C-e h o= (=M-x org-html-export-to-html=)
will not require additional software to compare
original document and exported file.

Notice that comments are omitted. Curiously you
could export org file to an org file with
=C-c C-e O o= (=M-x org-org-export-to-org=).
The reason to use the function
could be that you would like to share an org file
or a subtree but prefer to strip comments that you
consider private and hardly helpful for someone else.

You might notice =@@org:text@@= magic around.
There is no point of exporting links working in Emacs only
to a PDF or HTML file. Instead of =org= other formats could be used:
=latex=, =html=, etc.

Manual: [[https://orgmode.org/manual/Exporting.html][Exporting]]@@org:, [[info:org#Exporting][internal docs]]@@.

* TODO Next steps [0/6]                                                :code:

Would you like to continue org mode tour?

- [ ] put cursor into this line and try
  =C-c C-c= (universal org-mode command)
- [ ] if you are not familiar with Emacs,
  tutorial =C-h t= could make you more familiar to keystrokes
  and terms that sometimes unusual in comparison to wide
  spread GUI applications
- [ ] There are a lot of other features of Org mode
  described in the manual (@@org:[[info:org][internal help]], @@[[https://orgmode.org/manual/index.html][web site]],
  personally I prefer [[https://orgmode.org/org.html][single-file variant]]).
- [ ] Maybe you would like to read [[https://orgmode.org/guide/][compact guide]] at first.
- [ ] in respect to note taking you could be especially
  interested in [[https://orgmode.org/manual/Capture.html][capture templates]]@@org: on the web site or in [[info:org#capture][internal help]]@@
- [ ] Check =M-x org-version= message and compare
  with latest available stable version. E.g. on Debian
  and Ubuntu you could install =elpa-org= org package
  using apt. It provides org-mode newer than version
  shipped with emacs package but certainly behind upstream updates.

  #+begin_src bash :results none
    sudo apt install elpa-org
  #+end_src

Manual: [[https://orgmode.org/manual/TODO-Items.html][TODO Items]]@@org:, [[info:org#TODO Items][internal docs]]@@.

* Final note

Probably you would like to know how to save changes
you have made in a file. Readers achieved this point
deserves to know that. Use =C-x C-s=.
If it was vi, the user tried it for the first time
likely would worry if it is possible to escape from
the that first full screen editor.

Visit [[https://orgmode.org]] to discover more resources related
to org-mode.