Wiki > DocBook guidelines

[Stuart Ellis]

Page is here:

http://www.fedoraproject.org/wiki/DocsProject/WritingUsingTheWiki

The two issues:

- Markup for <filename>, <command>, <application>, etc. Following the
discussion in the FDSCo meeting I've currently specified monospace
(backticks) for all of them. The export renders this as
<code>whatever</code>.

One advantage of monospace over italics is that it isn't used in other
contexts. It also looks more like the final document.

- Referencing one document section from another. For want of any better
options, I'm inclined to use the name of the document section in
monospace here, because it isn't ambiguous for humans.

This is an issue for both single page or multiple-page documents.
MoinMoin does not seem to support internal section links within a page.
Links to other Wiki pages that are also part of the same document become
invalid on export. For example, as Wiki:

== Understanding the Directory Structure ==

yada yada ya

Refer to ../ManagingStorage for details of how to attach drives and disk
partitions to your filesystem.


MoinMoin > DocBook conversion:

<section>
<title>Understanding the Directory Structure</title>

<para>
yada yada ya
</para>

<para>
<ulink
url="/Docs/Drafts/AdministrationGuide/ManagingStorage">../ManagingStorage</ulink>
</para>

Valid DocBook document:

<title>Understanding the Directory Structure</title>

<para>
yada yada ya
</para>

<para>
Refer to <xref linkend="ch-managing-storage" /> for details of how to
attach drives and disk partitions to your filesystem.
</para>


-- 

Stuart Ellis

stuart at elsn.org

Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

GPG key ID: 7098ABEA
GPG key fingerprint: 68B0 E291 FB19 C845 E60E  9569 292E E365 7098 ABEA 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20051002/aaf0f291/attachment.sig>