From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id 6MIvIH64Ml9rTQAA0tVLHw (envelope-from ) for ; Tue, 11 Aug 2020 15:25:50 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1 with LMTPS id QLtsGn64Ml+eCwAAbx9fmQ (envelope-from ) for ; Tue, 11 Aug 2020 15:25:50 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id C3C3E9400BB for ; Tue, 11 Aug 2020 15:25:49 +0000 (UTC) Received: from localhost ([::1]:46454 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1k5W9s-0005LL-FG for larch@yhetil.org; Tue, 11 Aug 2020 11:25:48 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:55118) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5W9F-0005Jz-UI for emacs-orgmode@gnu.org; Tue, 11 Aug 2020 11:25:09 -0400 Received: from static.214.254.202.116.clients.your-server.de ([116.202.254.214]:33894 helo=ciao.gmane.io) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1k5W9D-0001hS-80 for emacs-orgmode@gnu.org; Tue, 11 Aug 2020 11:25:09 -0400 Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1k5W99-0008pX-Cw for emacs-orgmode@gnu.org; Tue, 11 Aug 2020 17:25:03 +0200 X-Injected-Via-Gmane: http://gmane.org/ To: emacs-orgmode@gnu.org From: Maxim Nikulin Subject: Re: Website revamp? Date: Tue, 11 Aug 2020 22:24:56 +0700 Message-ID: References: <87zh95g2ns.fsf@gmail.com> <87mu3hduk1.fsf@gmail.com> <87wo2lyvid.fsf@gnu.org> <87k0yldpuj.fsf@gmail.com> <20200730172204.GB17223@volibear> <87ime4ev3s.fsf@gmail.com> <20200730190331.GD17223@volibear> <878seyhj38.fsf@gmail.com> <87bljs6hph.fsf@gmail.com> <87r1so2u2b.fsf@yandex.com> <875za05l7v.fsf@gmail.com> <875z9y4cma.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 7bit User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0 In-Reply-To: <875z9y4cma.fsf@gmail.com> Content-Language: en-US Received-SPF: pass client-ip=116.202.254.214; envelope-from=geo-emacs-orgmode@m.gmane-mx.org; helo=ciao.gmane.io X-detected-operating-system: by eggs.gnu.org: First seen = 2020/08/11 08:55:58 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: 43 X-Spam_score: 4.3 X-Spam_bar: ++++ X-Spam_report: (4.3 / 5.0 requ) BAYES_00=-1.9, DKIM_ADSP_CUSTOM_MED=0.001, FORGED_GMAIL_RCVD=1, FORGED_MUA_MOZILLA=2.309, FREEMAIL_FORGED_FROMDOMAIN=1, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=1, NML_ADSP_CUSTOM_MED=0.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: "Emacs-orgmode" X-Scanner: scn0 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=fail reason="SPF not aligned (relaxed), No valid DKIM" header.from=gmail.com (policy=none); spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Spam-Score: 0.59 X-TUID: i9pUvOj3PyHK 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.