worg/worg-editing.org

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

Conventions

To-do keywords

:PROPERTIES: :CUSTOM_ID: worg-conventions :END:

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 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:

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:

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. See for example the dynamic block for the timestamp in the 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:worg.css::org-info-box][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 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