worg-editing.org

   1 #+EMAIL:      mdl AT imapmail DOT org
   2 #+TITLE:      How to edit Worg files?
   3 #+AUTHOR:     Worg people
   4 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   5 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   6 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   7 #+LANGUAGE:   en
   8 #+PRIORITIES: A C B
   9 #+CATEGORY:   worg
  10 #+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
  11 #+HTML_LINK_UP:    index.html
  12 #+HTML_LINK_HOME:  https://orgmode.org/worg/
  13
  14 # This file is released by its authors and contributors under the GNU
  15 # Free Documentation license v1.3 or later, code examples are released
  16 # under the GNU General Public License v3 or later.
  17
  18 Since Worg is just starting now, these conventions are just suggestions,
  19 not recommendations.  Please improve this.
  20
  21 * Conventions
  22   :PROPERTIES:
  23   :CUSTOM_ID: worg-conventions
  24   :END:
  25 ** To-do keywords
  26
  27 Here is a table with default to-do keywords and their meaning.
  28
  29 | To-do keyword | Meaning                                  |
  30 |---------------+------------------------------------------|
  31 | TODO(t)       | Things to do                             |
  32 | INPROGRESS(i) | Thing being in the process of being done |
  33 | WAITING(w@)   | Tasks stuck at some point                |
  34 | DONE(d)       | Completed task                           |
  35 | CANCELED(c@)  | Canceled task                            |
  36
  37 Feel free to discuss the relevance of these keywords and propose
  38 changes.
  39
  40 ** Tags
  41
  42 : Write(w) Update(u) Fix(f) Check(c)
  43
  44 ** Encoding
  45 ** Properties
  46 ** Link abbrevations
  47 ** Conventions about content?
  48   :PROPERTIES:
  49   :CUSTOM_ID: conventions-about-content
  50   :END:
  51
  52 Where you want to follow a documentation convention you may consider the
  53 [[https://code.orgmode.org/bzg/org-mode/raw/master/doc/Documentation_Standards.org][Org documentation standards]].
  54
  55 ** How rigid are these conventions?
  56
  57 (Suggestion: the farther from the index page you are, the more flexible
  58 the conventions should perhaps be.)
  59
  60 * How do I link to other Worg files?
  61   :PROPERTIES:
  62   :CUSTOM_ID: creating-links
  63   :END:
  64
  65 Links to other Worg pages should have the following format:
  66
  67 : [[file:index.org][Worg's home page]]
  68
  69 This link will converted to a relative html link on export that looks
  70 like this:
  71
  72 [[file:index.org][Worg's home page]]
  73
  74 The filename should be a relative path. Thus, if you are creating a
  75 link to the index from within the org-tutorials directory, you should
  76 enter the path as follows:
  77
  78 : [[file:../index.org][Worg's home page]]
  79
  80 The easiest way to create links to files is by typing =C-c C-l= while
  81 editing an org file. This will prompt you for both components of the
  82 link. (Be sure to enter =file:= before the path; this indicates the
  83 type of link.)
  84
  85 To enter file links more easily, you can simply type =C-u C-c C-l=. This
  86 will allow you to locate the file using emacs' built-in completion
  87 facilities and will automatically add the =file:= prefix.
  88
  89 One note of caution here: the path of the resulting link created
  90 depends on the setting of =org-link-file-path-type=. To ensure that you
  91 always use relative links, you can add the following to your =.emacs=
  92 file:
  93
  94 #+begin_src emacs-lisp
  95 (setq org-link-file-path-type 'relative)
  96 #+end_src
  97
  98 See also: [[info:org#External%20links][External links]] in the Org manual for details on how to link
  99 to a specific location within another Worg page.
 100
 101 * What is the default header for new files?
 102
 103 You can find a default header here: [[file:worg-header.org][worg-header.org]]
 104
 105 * How do I create a file?
 106
 107 Just create it.  Before committing changes in Worg, make sure you add
 108 the file to the repository index with =git add *.org=.
 109
 110 * What about dynamic blocks
 111
 112 If you are using dynamic blocks in Worg, please don't forget to add the
 113 relevant code in the [[file:code/elisp/worg.el][code/elisp/worg.el]] file.  See for example the dynamic
 114 block for the timestamp in the [[file:index.org][index]] page.
 115
 116 * What about macros
 117
 118 If you are using macros, please add them to =macros.setupfile=.
 119
 120 ** COMMENT Defined macros explained
 121
 122 *** Environments
 123
 124     - BeginMiniPage ... EndMiniPage :: creates a mini page with a border. Used to
 125          demonstrate layouts (see: [[file:./org-tutorials/images-and-xhtml-export.org]] for
 126          an example).
 127
 128     - BeginInfoBox ... EndInfoBox :: inserts a box with a little info icon on the
 129          left. The text inside flows around the icon. Both, info and warning boxes,
 130          use the styles for =.org-info-box= in [[file:worg.css::org-info-box][worg.css]].
 131
 132     - BeginWarningBox ... EndWarningBox :: Like =BeginInfoBox= and =EndInfoBox=. The
 133          icon used is different.
 134
 135     - BeginBlindText ... EndBlindText :: creates a =<span></span>= element, that
 136          greys out the text. Used for text that is there just to fill paragraphs
 137          to demonstrate text flow (see:
 138          [[file:./org-tutorials/images-and-xhtml-export.org]] for an example).
 139
 140 * How do I link to the Org version of the file?
 141
 142 The raw Org versions of the files are published [[https://orgmode.org/worg/sources/][here]].
 143
 144 * COMMENT How do I rename a file?
 145 * COMMENT Can I create a directory?
 146 * COMMENT What about non-org files in the repository?
 147
 148 .el files ?
 149 .pdf files