~bzg/worg

ref: 559025d3195c39306b5a5546c06a4e375fe4ff7f worg/worg-editing.org -rw-r--r-- 5.1 KiB
559025d3Bastien org-contribute.org: Add a note to maintainers 3 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
#+TITLE:      How to edit Worg files?
#+AUTHOR:     Worg people
#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
#+TAGS:       Write(w) Update(u) Fix(f) Check(c)
#+LANGUAGE:   en
#+PRIORITIES: A C B
#+CATEGORY:   worg
#+OPTIONS:    H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
#+HTML_LINK_UP:    index.html
#+HTML_LINK_HOME:  https://orgmode.org/worg/

# This file is released by its authors and contributors under the GNU
# Free Documentation license v1.3 or later, code examples are released
# under the GNU General Public License v3 or later.

Since Worg is just starting now, these conventions are just suggestions,
not recommendations.  Please improve this.

* Conventions
  :PROPERTIES:
  :CUSTOM_ID: worg-conventions
  :END:
** To-do keywords

Here is a table with default to-do keywords and their meaning.

| To-do keyword | Meaning                                  |
|---------------+------------------------------------------|
| TODO(t)       | Things to do                             |
| INPROGRESS(i) | Thing being in the process of being done |
| WAITING(w@)   | Tasks stuck at some point                |
| DONE(d)       | Completed task                           |
| CANCELED(c@)  | Canceled task                            |

Feel free to discuss the relevance of these keywords and propose
changes.

** Tags

: Write(w) Update(u) Fix(f) Check(c)

** Encoding
** Properties
** Link abbrevations
** Conventions about content?
  :PROPERTIES:
  :CUSTOM_ID: conventions-about-content
  :END:

Where you want to follow a documentation convention you may consider the
[[https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/doc/Documentation_Standards.org][Org documentation standards]].

** How rigid are these conventions?

(Suggestion: the farther from the index page you are, the more flexible
the conventions should perhaps be.)

* How do I link to other Worg files?
  :PROPERTIES:
  :CUSTOM_ID: creating-links
  :END:

Links to other Worg pages should have the following format:

: [[file:index.org][Worg's home page]]

This link will converted to a relative html link on export that looks
like this:

[[file:index.org][Worg's home page]]

The filename should be a relative path. Thus, if you are creating a
link to the index from within the org-tutorials directory, you should
enter the path as follows:

: [[file:../index.org][Worg's home page]]

The easiest way to create links to files is by typing =C-c C-l= while
editing an org file. This will prompt you for both components of the
link. (Be sure to enter =file:= before the path; this indicates the
type of link.)

To enter file links more easily, you can simply type =C-u C-c C-l=. This
will allow you to locate the file using emacs' built-in completion
facilities and will automatically add the =file:= prefix.

One note of caution here: the path of the resulting link created
depends on the setting of =org-link-file-path-type=. To ensure that you
always use relative links, you can add the following to your =.emacs=
file:

#+begin_src emacs-lisp
(setq org-link-file-path-type 'relative)
#+end_src

See also: [[info:org#External links][External links]] in the Org manual for details on how to link
to a specific location within another Worg page.

* What is the default header for new files?

You can find a default header here: [[file:worg-header.org][worg-header.org]]

* How do I create a file?

Just create it.  Before committing changes in Worg, make sure you add
the file to the repository index with =git add *.org=.

* What about dynamic blocks

If you are using dynamic blocks in Worg, please don't forget to add the
relevant code in the [[file:code/elisp/worg.el][code/elisp/worg.el]] file.  See for example the dynamic
block for the timestamp in the [[file:index.org][index]] page.

* What about macros

If you are using macros, please add them to =macros.setupfile=.

** COMMENT Defined macros explained

*** Environments

    - BeginMiniPage ... EndMiniPage :: creates a mini page with a border. Used to
         demonstrate layouts (see: [[file:./org-tutorials/images-and-xhtml-export.org]] for
         an example).

    - BeginInfoBox ... EndInfoBox :: inserts a box with a little info icon on the
         left. The text inside flows around the icon. Both, info and warning boxes,
         use the styles for =.org-info-box= in [[file:style/worg.css][worg.css]].

    - BeginWarningBox ... EndWarningBox :: Like =BeginInfoBox= and =EndInfoBox=. The
         icon used is different.

    - BeginBlindText ... EndBlindText :: creates a =<span></span>= element, that
         greys out the text. Used for text that is there just to fill paragraphs
         to demonstrate text flow (see:
         [[file:./org-tutorials/images-and-xhtml-export.org]] for an example).

* How do I link to the Org version of the file?

The raw Org versions of the files are published [[https://orgmode.org/worg/sources/][here]].

* COMMENT How do I rename a file?
* COMMENT Can I create a directory?
* COMMENT What about non-org files in the repository?

.el files ?
.pdf files