From 76213f982cabb99bf8df9d0429c4685a45a702a2 Mon Sep 17 00:00:00 2001 From: nikolaiam Date: Mon, 9 Jan 2017 14:11:54 +0200 Subject: [PATCH] Fix export-breaking org links in documentation As discussed in #8054 and #8136, org doesn't always export links correctly if the syntax deviates from the one given on the org mode website. This results in broken links on github and/or spacemacs.org as in #6722, #8036, #8054, #7956 and possibly others. This modifies all links not already fixed in #8136. Internal links are handled with Custom IDs. External file links are formatted according to org guidelines as well (see bottom), and if they point to a specific headline in an external file, a custom ID is created as well. Fixes #6722, #8036, #7956, #7916 as well as other unreported broken links. http://orgmode.org/manual/External-links.html#External-links http://orgmode.org/manual/Internal-links.html#Internal-links TODO: make Custom IDs invisble in space-org-mode --- doc/DOCUMENTATION.org | 67 ++++++++++++++++++++++++++++++++----------- doc/FAQ.org | 6 ++++ doc/LAYERS.org | 6 ++++ doc/QUICK_START.org | 6 ++-- doc/VIMUSERS.org | 41 +++++++++++++++++--------- 5 files changed, 93 insertions(+), 33 deletions(-) diff --git a/doc/DOCUMENTATION.org b/doc/DOCUMENTATION.org index 33c2e1658..9c7d7c2e1 100644 --- a/doc/DOCUMENTATION.org +++ b/doc/DOCUMENTATION.org @@ -260,7 +260,7 @@ project. * Who can benefit from this? - Spacemacs was initially intended to be used by *Vim users* who want to go to - the next level by using Emacs (see [[./VIMUSERS.org][guide]] for Vimmers). But it is now + the next level by using Emacs (see [[file:VIMUSERS.org][guide]] for Vimmers). But it is now perfectly *usable by non Vim users* by choosing the =emacs= editing style. - It is also a good fit for people wanting to *lower the [[http://en.wikipedia.org/wiki/Repetitive_strain_injury][risk of RSI]]* induced by @@ -325,6 +325,9 @@ and choosing a rollback slot (sorted by date). This button uses the command =configuration-layer/rollback=. * Configuration layers + :PROPERTIES: + :CUSTOM_ID: configuration-layers + :END: This section is an overview of layers. A more extensive introduction to writing configuration layers can be found [[file:LAYERS.org][here]] (recommended reading!). @@ -458,7 +461,7 @@ guidelines first in [[file:../CONTRIBUTING.org][CONTRIBUTING]]. ** Example: Themes Megapack example This is a simple configuration layer listing a bunch of themes which you can -find [[../layers/+themes/themes-megapack/README.org][here]]. +find [[file:../layers/+themes/themes-megapack/README.org][here]]. To install it, just add =themes-megapack= to your =~/.spacemacs= like so: @@ -501,6 +504,9 @@ Please refer to [[file:LAYERS.org][this]] introduction for some tips on writing best make them fit with the Spacemacs philosophy and loading strategy. * Dotfile Configuration +:PROPERTIES: +:CUSTOM_ID: dotfile-configuration +:END: User configuration can be stored in your =~/.spacemacs= file. ** Dotfile Installation @@ -598,7 +604,7 @@ to add some layers in =~/.myconfig=, set the variable like this: *** Setting configuration layers variables Some configuration layers have configuration variables to enable specific -feature. For instance the [[../layers/%2Bsource-control/git][git layer]] has several configuration variables, they +feature. For instance the [[file:../layers/+source-control/git/README.org][git layer]] has several configuration variables, they can be set directly in the =dotspacemacs-configuration-layers= like this: #+BEGIN_SRC emacs-lisp @@ -692,7 +698,7 @@ orphan so it is considered unused by Spacemacs). *** Excluding packages You can exclude packages you don't want to install with the variable -=dotspacemacs-excluded-packages= (see [[Configuration layers][Configuration layers]] for more info +=dotspacemacs-excluded-packages= (see [[#configuration-layers][Configuration layers]] for more info on packages). For instance, to disable the =rainbow-delimiters= package: @@ -785,6 +791,9 @@ To toggle the hybrid style on and off use ~SPC t E h~ and ~M-m t E h~. When off the =vim= style is enabled. ** States +:PROPERTIES: +:CUSTOM_ID: states +:END: Spacemacs has 10 states: | State | Default Color | Description | @@ -797,9 +806,9 @@ Spacemacs has 10 states: | replace | chocolate | exclusive to =Evil=, overwrites the character under point instead of inserting a new one | | hybrid | blue | exclusive to Spacemacs, this is like the insert state except that all the emacs key bindings are available | | evilified | light brown | exclusive to Spacemacs, this is an =emacs state= modified to bring Vim navigation, selection and search. | -| lisp | pink | exclusive to Spacemacs, used to navigate Lisp code and modify it (more [[Editing Lisp code][info]]) | -| iedit | red | exclusive to Spacemacs, used to navigate between multiple regions of text using =iedit= (more [[Replacing text with iedit][info]]) | -| iedit-insert | red | exclusive to Spacemacs, used to replace multiple regions of text using =iedit= (more [[Replacing text with iedit][info]]) | +| lisp | pink | exclusive to Spacemacs, used to navigate Lisp code and modify it (more [[#editing-lisp-code][info]]) | +| iedit | red | exclusive to Spacemacs, used to navigate between multiple regions of text using =iedit= (more [[#replacing-text-with-iedit][info]]) | +| iedit-insert | red | exclusive to Spacemacs, used to replace multiple regions of text using =iedit= (more [[#replacing-text-with-iedit][info]]) | Note: Technically speaking there is also the =operator= evil state. @@ -853,6 +862,9 @@ to ~SPC u~. pressing ~RETURN~. For instance: ~SPC SPC org-reload C-u RET~ ** Transient-states + :PROPERTIES: + :CUSTOM_ID: transient-states + :END: Spacemacs defines a wide variety of =transient states= (temporary overlay maps) where it makes sense. This prevents one from doing repetitive and tedious presses on the ~SPC~ key. @@ -862,7 +874,7 @@ minibuffer. Additional information may as well be displayed in the minibuffer. Auto-highlight-symbol transient state: [[file:img/spacemacs-ahs-transient-state.png]] -[[Text][Text scale transient state]]: +[[#text][Text scale transient state]]: [[file:img/spacemacs-scale-transient-state.png]] @@ -1268,7 +1280,7 @@ can be reached using the =control= key. | ~SPC t p~ | =ⓟ= | p | [[https://github.com/Fuco1/smartparens][smartparens]] mode | | ~SPC t C-p~ | =ⓟ= | p | global smartparens | | ~SPC t s~ | =ⓢ= | s | syntax checking (flycheck) | -| ~SPC t S~ | =Ⓢ= | S | enabled in [[../layers/+checkers/spell-checking][spell checking layer]] (flyspell) | +| ~SPC t S~ | =Ⓢ= | S | enabled in [[file:../layers/+checkers/spell-checking/README.org][spell checking layer]] (flyspell) | | ~SPC t w~ | =ⓦ= | w | whitespace mode | | ~SPC t C-w~ | =ⓦ= | w | global whitespace | | ~SPC t W~ | =Ⓦ= | W | automatic whitespace cleanup (see =dotspacemacs-whitespace-cleanup=) | @@ -1557,7 +1569,10 @@ If you find yourself unable to return focus to Helm (after a careless mouse-click for example), use ~SPC w b~ to return focus to the minibuffer. **** Helm transient state -Spacemacs defines a [[Transient-states][transient state]] for =Helm= to make it work like [[https://github.com/Shougo/unite.vim][Vim's Unite]] + :PROPERTIES: + :CUSTOM_ID: helm-transient-state + :END: +Spacemacs defines a [[#transient-states][transient state]] for =Helm= to make it work like [[https://github.com/Shougo/unite.vim][Vim's Unite]] plugin. Initiate the transient state with ~M-SPC~ or ~s-M-SPC~ while in a =Helm= buffer. @@ -1729,7 +1744,7 @@ Spacemacs. *** Toggles =helm-spacemacs-help= is also a central place to discover the available toggles. -To display only the toggles source press ~C-l~ (or in [[Helm transient state][Helm transient state]] you can +To display only the toggles source press ~C-l~ (or in [[#helm-transient-state][Helm transient state]] you can press just ~l~). The following helm actions are available on packages: @@ -2011,10 +2026,13 @@ the opened buffer and kill them. | Any other key | leave the transient state | **** Special Buffers +:PROPERTIES: +:CUSTOM_ID: special-buffers +:END: Unlike vim, emacs creates many buffers that most people do not need to see. Some examples are =*Messages*= and =*Compile-Log*=. Spacemacs tries to automatically ignore buffers that are not useful. However, you may want to change the way -Spacemacs marks buffers as useful. For instructions, see the [[file:FAQ.org::Change%20special%20buffer%20rules?][special buffer howto]]. +Spacemacs marks buffers as useful. For instructions, see the [[file:FAQ.org::#change-special-buffer-rules][special buffer howto]]. **** Files manipulations key bindings Files manipulation commands (start with ~f~): @@ -2098,7 +2116,7 @@ Basic =ido= operations can be done with ~Ctrl~ key: | ~C-S-l~ | go to next directory | *** Ido transient state -Spacemacs defines a [[Transient-states][transient state]] for =ido=. +Spacemacs defines a [[#transient-states][transient state]] for =ido=. Initiate the transient state with ~M-SPC~ or ~s-M-SPC~ while in an =ido= buffer. @@ -2419,6 +2437,9 @@ bindings (~SPC e n~ and ~SPC e p~) as well as the error transient state (~SPC e~ | ~SPC s t F~ | =pt= with default text | **** Searching in a project +:PROPERTIES: +:CUSTOM_ID: searching-in-a-project +:END: | Key Binding | Description | |-----------------------+-----------------------------------------------------| @@ -2509,7 +2530,7 @@ Where = [x/y]*= is: With [[https://github.com/bling/evil-visualstar][evil-visualstar]] you can search for the next occurrence of the current selection. -It is pretty useful combined with the [[Region selection][expand-region]] bindings. +It is pretty useful combined with the [[#expand-region][expand-region]] bindings. *Note*: If the current state is not the =visual state= then pressing ~*~ uses auto-highlight-symbol and its transient state. @@ -2634,6 +2655,9 @@ It is possible to enable it easily for /all programming modes/ with the variable *** Zooming **** Text + :PROPERTIES: + :CUSTOM_ID: text + :END: The font size of the current buffer can be adjusted with the commands: | Key Binding | Description | @@ -2687,7 +2711,7 @@ In transient state: argument (i.e. ~10 SPC n +~ will add 10 to the number under point). *** Spell checking -Spell checking is enabled by including the [[../layers/+checkers/spell-checking][spell +Spell checking is enabled by including the [[file:../layers/+checkers/spell-checking/README.org][spell checking]] layer in your dotfile. Keybindings are listed in the layer documentation. @@ -2696,6 +2720,9 @@ Keybindings are listed in the layer documentation. Vi =Visual= modes are all supported by =evil=. **** Expand-region +:PROPERTIES: +:CUSTOM_ID: expand-region +:END: Spacemacs adds another =Visual= mode via the [[https://github.com/magnars/expand-region.el][expand-region]] mode. | Key Binding | Description | @@ -2737,6 +2764,9 @@ The displayed text of a buffer can be narrowed with the commands (start with | ~SPC n w~ | widen, i.e. show the whole buffer again | *** Replacing text with iedit + :PROPERTIES: + :CUSTOM_ID: replacing-text-with-iedit + :END: Spacemacs uses the powerful [[https://github.com/tsdh/iedit][iedit]] mode through [[https://github.com/syl20bnr/evil-iedit-state][evil-iedit-state]] to quickly edit multiple occurrences of a symbol or selection. @@ -2898,6 +2928,9 @@ To disable the trash you can set the variable =delete-by-moving-to-trash= to =nil= in your =~/.spacemacs=. *** Editing Lisp code + :PROPERTIES: + :CUSTOM_ID: editing-lisp-code + :END: Editing of lisp code is provided by [[https://github.com/syl20bnr/evil-lisp-state][evil-lisp-state]]. Commands will set the current state to =lisp state= where different commands @@ -2998,7 +3031,7 @@ are defined implicitly, for instance the root of a project is found when a =Helm= is used whenever it is possible. -To search in a project see [[Searching in a project][project searching]]. +To search in a project see [[#searching-in-a-project][project searching]]. =projectile= commands start with p: @@ -3028,7 +3061,7 @@ To search in a project see [[Searching in a project][project searching]]. | ~SPC p T~ | test project | | ~SPC p v~ | open project root in =vc-dir= or =magit= | | ~SPC /~ | search in project with the best search tool available | -| ~SPC s p~ | see [[Searching in a project][search in project]] | +| ~SPC s p~ | see [[#searching-in-a-project][searching in a project]] | | ~SPC s a p~ | run =ag= | | ~SPC s g p~ | run =grep= | | ~SPC s k p~ | run =ack= | diff --git a/doc/FAQ.org b/doc/FAQ.org index dbaac721d..0e69017a3 100644 --- a/doc/FAQ.org +++ b/doc/FAQ.org @@ -263,6 +263,9 @@ the list =dotspacemacs-excluded-packages= if you prefer setting =exec-path= yourself. * How do I: +:PROPERTIES: +:CUSTOM_ID: how-do-i +:END: ** Install a package not provided by a layer? Spacemacs provides a variable in the =dotspacemacs/layers= function in =.spacemacs= called =dotspacemacs-additional-packages=. Just add a package name @@ -301,6 +304,9 @@ dotfile. The following snippet disables company for =python-mode=: #+END_SRC ** Change special buffer rules? + :PROPERTIES: + :CUSTOM_ID: change-special-buffer-rules + :END: To change the way spacemacs marks buffers as useless, you can customize =spacemacs-useless-buffers-regexp= which marks buffers matching the regexp as useless. The variable =spacemacs-useful-buffers-regexp= marks buffers matching diff --git a/doc/LAYERS.org b/doc/LAYERS.org index bdce140c9..d4878ebb2 100644 --- a/doc/LAYERS.org +++ b/doc/LAYERS.org @@ -273,6 +273,9 @@ Use-package supports heaps of useful keywords. Look at the [[https://github.com/ more. * Anatomy of a layer +:PROPERTIES: +:CUSTOM_ID: anatomy-of-a-layer +:END: A layer is simply a folder somewhere in Spacemacs' layer search path that usually contains these files (listed in loading order). @@ -495,6 +498,9 @@ hooks, if the package should be loaded upon some event. It is not unusual to have both! ** Use-package hooks +:PROPERTIES: +:CUSTOM_ID: use-package-hooks +:END: Spacemacs includes a macro for adding more code to the =:init= or =:config= blocks of a call to =use-package=, after the fact. This is useful for =pre-init= or =post-init= functions to "inject" code into the =use-package= call of the diff --git a/doc/QUICK_START.org b/doc/QUICK_START.org index dd35ba64a..f7ff5a293 100644 --- a/doc/QUICK_START.org +++ b/doc/QUICK_START.org @@ -80,8 +80,8 @@ dotspacemacs-configuration-layers '(auto-completion At anytime you can apply the changes made to the dotfile or layers _without restarting_ Spacemacs by pressing ~SPC f e R~. -The [[file:../core/templates/.spacemacs.template][dotfile template]] contain further information about how to customize -Spacemacs. See the dotfile configuration section of the [[file:DOCUMENTATION.org][documentation]] for +The [[https://github.com/syl20bnr/spacemacs/blob/master/core/templates/.spacemacs.template][dotfile template]] contains further information about how to customize +Spacemacs. See the dotfile configuration section of the [[file:DOCUMENTATION.org::#dotfile-configuration][documentation]] for more details. * Dotdirectory (~/.spacemacs.d) @@ -174,4 +174,4 @@ about functions, variables, modes etc. These commands are bound thusly: | ~SPC h d v~ | describe-variable | * How-To's -Some quick =how-to's= are compiled in the [[file:FAQ.org::How%20do%20I...][FAQ.org]] file. +Some quick =how-to's= are compiled in the [[file:FAQ.org::#how-do-i][FAQ.]] diff --git a/doc/VIMUSERS.org b/doc/VIMUSERS.org index 39820ecad..86bf70e61 100644 --- a/doc/VIMUSERS.org +++ b/doc/VIMUSERS.org @@ -60,7 +60,7 @@ for new users. This section attempts to clear up any confusion. *** Modes vs. States In vim you have various editing modes like =insert mode= and =visual mode= to -manipulate text. In Emacs, we have [[./DOCUMENTATION.org#states][states]]. These are equivalent to vim modes. +manipulate text. In Emacs, we have [[file:DOCUMENTATION.org::#states][states]]. These are equivalent to vim modes. For example, =evil-insert-state= is the same as =insert-mode= in vim. A =minor-mode= in Emacs is like a feature that is activated. For example, @@ -79,8 +79,8 @@ several packages that integrate well with each other. For example, the =python= layer includes support for auto-completion, documentation look-up, tests, and much more by using several different packages. This keeps you from thinking about what packages to install, and instead worry about what features you want. -More information on layers can be found in the [[./VIMUSERS.org#customization][customization]] section and in the -[[./DOCUMENTATION.org#configuration-layers][documentation]]. There is also a more in-depth guide on writing layers [[file:LAYERS.org][here]]. +More information on layers can be found in the [[#customization][customization]] section and in the +[[file:DOCUMENTATION.org::#configuration-layers][documentation]]. There is also a more in-depth guide on writing layers [[file:LAYERS.org][here]]. *** Transient-states Spacemacs provides a special functionality called transient-states. Transient-states @@ -99,7 +99,7 @@ Spacemacs uses ~SPC~ as its ~~ key. This document will use ~SPC~ to refe the ~~ key. All keybindings are mnemonic and are organized under the ~~ key. For example, the keybindings for language-specific commands are always under the ~SPC m~ prefix. A full list of conventions used in Spacemacs is -[[./CONVENTIONS.org][here]]. Note that all keybindings can be changed. +[[file:CONVENTIONS.org][here]]. Note that all keybindings can be changed. Spacemacs uses [[https://github.com/justbur/emacs-which-key][which-key]] to show available keybindings after a delay: @@ -124,17 +124,20 @@ are located under the ~SPC b~ prefix. |---------------------------+------------------------------------------------------| | ~SPC b b ~ | Create a buffer named ==. | | ~SPC b b~ | Search through open buffers and recent files. | -| ~SPC b n~ or ~:bnext~ | Switch to the next buffer. (See [[*Special%20buffers][Special buffers]]) | -| ~SPC b p~ or ~:bprevious~ | Switch to the previous buffer. (See [[*Special%20buffers][Special buffers]]) | +| ~SPC b n~ or ~:bnext~ | Switch to the next buffer. (See [[#special-buffers][Special buffers]]) | +| ~SPC b p~ or ~:bprevious~ | Switch to the previous buffer. (See [[#special-buffers][Special buffers]]) | | ~SPC b d~ or ~:bdelete~ | Kill current buffer. | | ~SPC b C-d~ | Kill buffers using a regular expression. | | ~SPC b m~ | Kill all buffers except the current buffer. | | ~SPC b .~ | Buffer transient-state. | **** Special buffers +:PROPERTIES: +:CUSTOM_ID: special-buffers +:END: By default Emacs creates a lot of buffers that most people will never need, like =*Messages*=. Spacemacs automatically ignores these when using these -key bindings. More information can be found [[./DOCUMENTATION.org#special-buffers][here]]. +key bindings. More information can be found [[file:DOCUMENTATION.org::#special-buffers][here]]. *** Windows Windows are like splits in vim. They are useful for editing multiple files at @@ -187,6 +190,9 @@ explore: | ~SPC ?~ | Lists all keybindings. | * Customization +:PROPERTIES: +:CUSTOM_ID: customization +:END: ** The .spacemacs file When you first start spacemacs, you will be prompted to choose an editing style. If you are reading this, you likely want to choose the vim style. A =.spacemacs= @@ -286,6 +292,9 @@ Here is an example of a function that is useful in real life: #+end_src ** Activating a Layer +:PROPERTIES: +:CUSTOM_ID: activating-a-layer +:END: As said in the terms section, layers provide an easy way to add features. Activating a layer is done in the =.spacemacs= file. In the file search for the =dotspacemacs-configuration-layers= variable. By default, it should look like @@ -358,16 +367,16 @@ execute code before or after a package loads. It would look like this: **Note**: Only one layer can have a =init= function for a package. If you want to override the configuration of a package in another layer, use a -=/pre-init= function in addition to [[file:LAYERS.org#use-package-hooks][use-package hooks]]. +=/pre-init= function in addition to [[file:LAYERS.org::#use-package-hooks][use-package hooks]]. If a package is not available on MELPA, you must use a local package or a -package recipe. For more details see [[file:LAYERS.org#anatomy-of-a-layer][anatomy of a layer]]. +package recipe. For more details see [[file:LAYERS.org::#anatomy-of-a-layer][anatomy of a layer]]. -Make sure you [[Activating a Layer][add]] your layer to your =.spacemacs= file and restart to +Make sure you [[#activating-a-layer][add]] your layer to your =.spacemacs= file and restart to activate it. A detailed description of the loading process and how layers work can be found in -[[file:LAYERS.org][LAYERS.org]]. +the [[file:LAYERS.org][configuration layers documentation.]] ** Installing a single package Sometimes creating a layer is a bit overkill. Maybe you just want one package @@ -375,9 +384,12 @@ and don't want to maintain a whole layer. Spacemacs provides a variable in the =dotspacemacs/layers= function in =.spacemacs= called =dotspacemacs-additional-packages=. Just add a package name to the list and it will be installed when you restart. Loading the package is covered in the next -[[Loading packages][section]]. +[[#loading-packages][section]]. ** Loading packages +:PROPERTIES: +:CUSTOM_ID: loading-packages +:END: Ever wonder how Spacemacs can load over a 100 packages in just a few seconds? Such low loading times must require some kind of unreadable black magic that no one can understand. Thanks to [[https://github.com/jwiegley/use-package][use-package]], this is not true. It is a package @@ -410,6 +422,9 @@ This is just a very basic overview of =use-package=. There are many other ways to control how a package loads using it that aren't covered here. ** Uninstalling a package +:PROPERTIES: +:CUSTOM_ID: uninstalling-a-package +:END: Spacemacs provides a variable in the =dotspacemacs/init= function in =.spacemacs= called =dotspacemacs-excluded-packages=. Just add a package name to the list and it will be uninstalled when you restart. @@ -457,7 +472,7 @@ when you are not navigating between them. You can use ~SPC s c~ or ~:nohlsearch~ to disable search result highlighting. To disable the result highlighting when it is not needed anymore automatically, -you can [[Uninstalling a package][uninstall]] the =evil-search-highlight-persist= package. +you can [[#uninstalling-a-package][uninstall]] the =evil-search-highlight-persist= package. *** Sessions Spacemacs does not automatically restore your windows and buffers when you