Merge pull request #3801 from jeetelongname/develop

Update docs for doom-quit, ligatures & hl-todo

modules/ui/doom-quit/README.org

@@ -3,6 +3,37 @@
 #+SINCE:   v2.0
 #+STARTUP: inlineimages
 
+* Table of Contents :TOC_3:noexport:
+- [[#description][Description]]
+  - [[#module-flags][Module Flags]]
+  - [[#plugins][Plugins]]
+- [[#prerequisites][Prerequisites]]
+- [[#features][Features]]
+- [[#configurations][Configurations]]
+- [[#troubleshooting][Troubleshooting]]
+
+* Description
 A silly module that prompts you with messages when you try to quit, like DOOM
 did. Some quotes are from Doom's quit-message list. Others are random, nerdy
-references that no decent human being has any business recognizing.
+references that no decent human being has any business recognising.
+** Module Flags
+This module provides no flags
+** Plugins
+This module uses no Plugins
+* Prerequisites
+This module provides no prerequisite
+* Features
+This module only works when you run individual Emacs instances and not the
+daemon.
+* Configurations
+ you can configure the messages by adding to the variable ~+doom-quit-messages~
+ #+BEGIN_SRC emacs-lisp
+(setq +doom-quit-messages '(;;from doom 2
+                            "Don't go now, there's a dimensional shambler waiting at the dos prompt!"
+                            "Get outta here and go back to your boring programs."
+                            "If I were your boss, I'd deathmatch ya in a minute!"
+                            "Look, bud. You leave now and you forfeit your body count!"
+                            "You're lucky I don't smack you for thinking about leaving."))
+ #+END_SRC
+* Troubleshooting
+If you have any issues with this module do let me know

modules/ui/hl-todo/README.org

@@ -1,13 +1,83 @@
 #+TITLE: :ui hl-todo
+#+DATE:    February 19, 2017
+#+SINCE:   v1.3
+#+STARTUP: inlineimages
 
-This module adds syntax highlighting for TODO/FIXME/NOTE tags in programming major-modes.
+* Table of Contents :TOC_3:noexport:
+- [[#description][Description]]
+  - [[#module-flags][Module Flags]]
+  - [[#plugins][Plugins]]
+- [[#prerequisites][Prerequisites]]
+- [[#features][Features]]
+  - [[#making-items][Making Items]]
+  - [[#keybindings][Keybindings]]
+  - [[#adding-items][Adding items.]]
+- [[#configuration][Configuration]]
+- [[#troubleshooting][Troubleshooting]]
 
-What keywords are highlighted (and their color) can be customized through ~hl-todo-keyword-faces~.
+* Description
+This module adds syntax highlighting for TODO/FIXME/NOTE tags in programming
+major-modes.
 
+** Module Flags
+This module provides no flags
+
+** Plugins
++ [[https://github.com/tarius/hl-todo][hl-todo]]
+ 
+* Prerequisites
+This module has no prerequisites
+
+* Features
+
+** Making Items
+You can make a TODO item by simply writing
++ =TODO=
+  For things that need to be done, just not today.
++ =HACK=
+  For tidbits that are unconventional and not intended uses of the
+  constituent parts, and may break in a future update.
++ =FIXME=
+  For problems that will become bigger problems later if not fixed ASAP.
++ =REVIEW=
+  for things that were done hastily and/or hasn't been thoroughly
+  tested. it may not even be necessary!
++ =NOTE=
+  For especially important gotchas with a given implementation,
+  directed at another user other than the author.
++ =DEPRECATED=
+  For things that just gotta go and will soon be gone.
++ =BUG=
+  For a known bug that needs a workaround
++ =XXX=
+  For warning about a problematic or misguiding code
+
+** Keybindings
+| keybind   | description                      |
+|-----------+----------------------------------|
+| =]t=      | go to next TODO item             |
+| =[t=      | go to previous TODO item         |
+| =SPC p t= | show all TODO items in a project |
+| =SPC s p= | search project for a string      |
+| =SPC s b= | search buffer for string         |
+
+** TODO Adding items.
+The way you would add a TODO item is to use a snippet but these have not been
+made. you can make them yourself by adding the snippet to
+=$DOOMDIR/snippets/MAJOR-MODE/name-of-snippet=. you will find more info on how
+to make them [[https://github.com/hlissner/doom-snippets][here]]
+
+* Configuration
+To add your own ITEMS you would need to configure them using
+~hl-todo-keyword-faces~
 #+BEGIN_SRC emacs-lisp
 ;; the default
-(setq hl-todo-keyword-faces
-      `(("TODO"  . ,(face-foreground 'warning))
-        ("FIXME" . ,(face-foreground 'error))
-        ("NOTE"  . ,(face-foreground 'success))))
+(after! hl-todo
+  (setq hl-todo-keyword-faces
+        `(
+          ("FOO"  . ,(face-foreground "MY COLOUR HEX CODE"))
+          ("BAR" . ,(face-foreground 'my-colour-var)))))
 #+END_SRC
+
+* TODO Troubleshooting
+If you have any problems with this module do get in touch!

modules/ui/ligatures/README.org

@@ -16,7 +16,8 @@
   - [[#mathematical-symbols-replacement][Mathematical symbols replacement]]
   - [[#coding-ligatures][Coding ligatures]]
 - [[#configuration][Configuration]]
-  - [[#set-ligatures][~set-ligatures!~]]
+  - [[#setting-ligatures][Setting ligatures]]
+  - [[#changing-ligatures][Changing ligatures]]
 - [[#troubleshooting][Troubleshooting]]
 
 * Description
@@ -101,8 +102,116 @@ Even though harfbuzz has been included in emacs 27, there is currently a [[https
 (#40864)]] which prevents a safe usage of /composition-function-table/ method in
 emacs 27.
 
-* TODO Configuration
-** TODO ~set-ligatures!~
+* Configuration
+** Setting ligatures
+If you want to set ligatures for modules that don't have them by default you can
+use the ~set-ligatures!~ macro in your config el file
+#+BEGIN_SRC emacs-lisp
+(after! PACKAGE
+  (set-ligatures! 'MAJOR-MODE
+    :symbol "keyword"))
+#+END_SRC
+eg.
+#+BEGIN_SRC emacs-lisp
+(after! go-mode ; in this case the major mode and package named the same thing
+  (set-ligatures! 'go-mode
+    :def "func" ; function keyword
+    :true "true" :false "false"
+    ; this will replace not only definitions
+    ; but coresponding functions aswell
+    :int "int" :str "string"
+    :float "float" :bool "bool"
+    :for "for"
+    :return "return" :yeild "yeild"))
+#+END_SRC
+you can set these symbols out of the box
+#+BEGIN_SRC emacs-lisp
+(set-ligatures! 'MAJOR-MODE
+    ;; Functional
+    :lambda        "lambda keyword"
+    :def           "function keyword"
+    :composition   "composition"
+    :map           "map/dictionary keyword"
+    ;; Types
+    :null          "null type"
+    :true          "true keyword"
+    :false         "false keyword"
+    :int           "int keyword"
+    :float         "float keyword"
+    :str           "string keyword"
+    :bool          "boolean keywork"
+    :list          "list keyword"
+    ;; Flow
+    :not           "not operator"
+    :in            "in operator"
+    :not-in        "not in operator"
+    :and           "and keyword"
+    :or            "or keyword"
+    :for           "for keyword"
+    :some          "some keyword"
+    :return        "return"
+    :yield         "yeild"
+    ;; Other
+    :union         "Union keyword"
+    :intersect     "Intersect keyword"
+    :diff          "diff keyword"
+    :tuple         "Tuple Keyword "
+    :pipe          "Pipe Keyword" ;; FIXME: find a non-private char
+    :dot           "Dot operator")
+#+END_SRC
+
+If you have multiple versions of the same keyword you can set the symbol twice
+
+#+BEGIN_SRC emacs-lisp
+(set-ligatures! scala-mode
+  :null "none"
+  :null "None")
+#+END_SRC
+** Changing ligatures
+if you don't like the symbols chosen you can change them by using...
+
+#+BEGIN_SRC emacs-lisp
+;; you don't need to include all of them you can pick and mix
+(plist-put +ligatures-extra-symbols
+  '(;; org
+    :name          "»"
+    :src_block     "»"
+    :src_block_end "«"
+    :quote         "“"
+    :quote_end     "”"
+    ;; Functional
+    :lambda        "λ"
+    :def           "ƒ"
+    :composition   "∘"
+    :map           "↦"
+    ;; Types
+    :null          "∅"
+    :true          "𝕋"
+    :false         "𝔽"
+    :int           "ℤ"
+    :float         "ℝ"
+    :str           "𝕊"
+    :bool          "𝔹"
+    :list          "𝕃"
+    ;; Flow
+    :not           "￢"
+    :in            "∈"
+    :not-in        "∉"
+    :and           "∧"
+    :or            "∨"
+    :for           "∀"
+    :some          "∃"
+    :return        "⟼"
+    :yield         "⟻"
+    ;; Other
+    :union         "⋃"
+    :intersect     "∩"
+    :diff          "∖"
+    :tuple         "⨂"
+    :pipe          "" ;; FIXME: find a non-private char
+    :dot           "•"))
+  ;; you could also add your own if you want
+#+END_SRC
 
 * TODO Troubleshooting
-# Common issues and their solution, or places to look for help.
+ If you have any problems with this module, do get in touch!