How to edit Worg files?
Since Worg is just starting now, these conventions are just suggestions, not recommendations. Please improve this.
Conventions
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)
Conventions about content?
Where you want to follow a documentation convention you may consider the Org documentation standards.
How do I link to other Worg files?
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:
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:
(setq org-link-file-path-type 'relative)
See also: 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: 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 code/elisp/worg.el file. See for example the dynamic block for the timestamp in the index page.
What about macros
If you are using macros, please add them to macros.setupfile.
Defined macros explained
Environments
- BeginMiniPage … EndMiniPage
- creates a mini page with a border. Used to demonstrate layouts (see: ./org-tutorials/images-and-xhtml-export.html 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
.infoboxin worg.css. - BeginWarningBox … EndWarningBox
- Like
BeginInfoBoxandEndInfoBox. 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: ./org-tutorials/images-and-xhtml-export.html for an example).
What about special blocks
Just like Environments, you can use special blocks for special highlighting:
- highlightbox
- A highlighted indented text box
- infobox
- A box with
image - warningbox
- A box with
image - minipage
- A bordered box
- blindtext
- Greyed-out text