Wiki editing refresher

For all who are editing the DUG or Docs/Beats/, a quick
reminder
pointer:

http://fedoraproject.org/wiki/WikiEditing#Marki
ng_Technical_Terms

http://fedoraproject.org/wiki/WikiEditing#Quick_Tips

Especially note the first, Marking Technical Terms.  There
is a table
there that is useful.  The entire Quick Tips section is good
to be
familiar with.

When it comes time to convert to XML, it is important to
have standard
usage from the Wiki.  It also helps the final Wiki edit in
preparation
for the XML conversion.

Thanks - Karsten
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation
Project 
 Sr. Developer Relations Mgr.     | 
fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key:
AD0E0C41
//////////////////////////////////
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
\\\\\\
-- 
fedora-docs-list mailing list
fedora-docs-listredhat.com
To unsubscribe: 
https://www.redhat.com/mailman/listinfo/fedora-docs-list

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


Karsten Wade wrote:
> For all who are editing the DUG or Docs/Beats/, a quick
reminder
> pointer:
> 
> http://fedoraproject.org/wiki/WikiEditing#Marki
ng_Technical_Terms
> 
http://fedoraproject.org/wiki/WikiEditing#Quick_Tips
> 
> Thanks - Karsten
> 

I've been working on converting the server guide (slowly)
and notice
that the wiki does not have all the functionality/style that
I need to
'easily' convert my guide to the LDP wiki - or I'm doing
it the wrong
way :-O.

As the guide is server based, most of the configuration is
done by
manually editing the files at the command line. I wanted to
make the
guide easy to follow, so I'd like to have a separate
format/style
differentiating between a typed command, the output of a
command, and
the contents of a configuration file - these seemed the most
common
choices for manual administration.

To move technical info (config files etc..) into the wiki
takes a large
amount of time using wiki markup, and displaying
configuration files
inside a table takes a fair bit to format, so it looks
similar to what
the user is expecting to see. To make it simpler, html -
<PRE> tags work
best, however the CSSs only provide one format/style for
<PRE> tags.

I loaded up moin on my own server so I could learn without
killing
anything on FDP and also to play with the CSSs/markup to get
the results
I think is suitable for the guide.

I've created a few pages and a template located here:
http://www.brennan.id.
au/wiki/
http://www.brennan.id.au/wiki/LinuxHomeServerTemplate
(Internet Explorer does not display my theme very well -
known fault)

Also, upgrading the guide should be easier when it is
superceded by the
next FC release, because the new example commands / output
can be copied
straight into the <PRE> tags again.

I just wanted to get your opinions in regards to the
formating/style of
the command line interaction and to see if it would break
anything
(docbook/CVS/XML conversion etc..).


Regards,
Miles Brennan
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (MingW32)

iD8DBQFE8bNvcSPa0xQu/fARAkivAJ40EDGO1974DS0I2ZPlH59k1tx9YwCd
HSp2
6PWVKKLpCa5pv4XY6GFWdkg=
=tEPn
-----END PGP SIGNATURE-----

-- 
fedora-docs-list mailing list
fedora-docs-listredhat.com
To unsubscribe: 
https://www.redhat.com/mailman/listinfo/fedora-docs-list

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


Karsten Wade wrote:
> For all who are editing the DUG or Docs/Beats/, a quick
reminder
> pointer:
> 
> http://fedoraproject.org/wiki/WikiEditing#Marki
ng_Technical_Terms
> 
http://fedoraproject.org/wiki/WikiEditing#Quick_Tips
> 
> Thanks - Karsten
> 

I've been working on converting the server guide (slowly)
and notice
that the wiki does not have all the functionality/style that
I need to
'easily' convert my guide to the LDP wiki - or I'm doing
it the wrong
way :-O.

As the guide is server based, most of the configuration is
done by
manually editing the files at the command line. I wanted to
make the
guide easy to follow, so I'd like to have a separate
format/style
differentiating between a typed command, the output of a
command, and
the contents of a configuration file - these seemed the most
common
choices for manual administration.

To move technical info (config files etc..) into the wiki
takes a large
amount of time using wiki markup, and displaying
configuration files
inside a table takes a fair bit to format, so it looks
similar to what
the user is expecting to see. To make it simpler, html -
<PRE> tags work
best, however the CSSs only provide one format/style for
<PRE> tags.

I loaded up moin on my own server so I could learn without
killing
anything on FDP and also to play with the CSSs/markup to get
the results
I think is suitable for the guide.

I've created a few pages and a template located here:
http://www.brennan.id.
au/wiki/
http://www.brennan.id.au/wiki/LinuxHomeServerTemplate
(Internet Explorer does not display my theme very well -
known fault)

Also, upgrading the guide should be easier when it is
superceded by the
next FC release, because the new example commands / output
can be copied
straight into the <PRE> tags again.

I just wanted to get your opinions in regards to the
formating/style of
the command line interaction and to see if it would break
anything
(docbook/CVS/XML conversion etc..).


Regards,
Miles Brennan
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2.2 (MingW32)

iD8DBQFE8bNvcSPa0xQu/fARAkivAJ40EDGO1974DS0I2ZPlH59k1tx9YwCd
HSp2
6PWVKKLpCa5pv4XY6GFWdkg=
=tEPn
-----END PGP SIGNATURE-----

-- 
fedora-docs-list mailing list
fedora-docs-listredhat.com
To unsubscribe: 
https://www.redhat.com/mailman/listinfo/fedora-docs-list

On Mon, 2006-08-28 at 00:59 +1000, Miles Brennan wrote:
> I've been working on converting the server guide
(slowly) and notice
> that the wiki does not have all the functionality/style
that I need to
> 'easily' convert my guide to the LDP wiki - or I'm
doing it the wrong
> way :-O.
> 
> As the guide is server based, most of the configuration
is done by
> manually editing the files at the command line. I
wanted to make the
> guide easy to follow, so I'd like to have a separate
format/style
> differentiating between a typed command, the output of
a command, and
> the contents of a configuration file - these seemed the
most common
> choices for manual administration.
> 
> To move technical info (config files etc..) into the
wiki takes a large
> amount of time using wiki markup, and displaying
configuration files
> inside a table takes a fair bit to format, so it looks
similar to what
> the user is expecting to see. To make it simpler, html
- <PRE> tags work
> best, however the CSSs only provide one format/style
for <PRE> tags.

This is exactly why using the Wiki is not the best way to do
technical
documentation.  DocBook is far better suited, because there
are tags to
support all these different usages:

<para>
  Here's my explanatory text about what happens
  when you run the <command>foosetup</command>
  command.  First, the following screen appears:
</para>
<screen>
  <computeroutput>Your setup of foo
    is complete.</computeroutput>
</screen>
<para>
  Then you can add the following line to the
  <filename>/etc/foo</filename> file:
</para>
<screen>
  <userinput>BAR=1</userinput>
</screen>

The wiki has no good way of converting these elements once
they're
properly tagged with DocBook anyway.  When we move to Plone,
there may
be a one-for-one conversion from DocBook in our CVS
repository to the
document in Plone -- or Plone might simply use the DocBook
XML "live,"
converting user editing as necessary.  I've no idea,
unfortunately.

For now, simply use the technical terms and you'll have to
rely on an
editor to tag your guide correctly with DocBook -- or you
could try
doing it yourself, using some of the starter information I
posted the
other day in our inaugural Munch 'N' Learn:

http://www.redhat.com/archives/fedora-d
ocs-list/2006-August/msg00081.html

DocBook is really very easy -- as easy as doing HTML or any
other markup
-- once you get started.  Most people only ever use a
handful of tags,
and add more to their "personal knowledge base"
as needed.  XML is
becoming (has become!) so widespread that it's almost
criminal *not* to
learn about it, and DocBook is just a specific type of XML
document.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937
BD11 3717
       Fedora Project Board: http://fedoraproj
ect.org/wiki/Board
    Fedora Docs Project:  http://fedo
raproject.org/wiki/DocsProject
-- 
fedora-docs-list mailing list
fedora-docs-listredhat.com
To unsubscribe: 
https://www.redhat.com/mailman/listinfo/fedora-docs-list

On Mon, 2006-08-28 at 00:59 +1000, Miles Brennan wrote:
> I've been working on converting the server guide
(slowly) and notice
> that the wiki does not have all the functionality/style
that I need to
> 'easily' convert my guide to the LDP wiki - or I'm
doing it the wrong
> way :-O.
> 
> As the guide is server based, most of the configuration
is done by
> manually editing the files at the command line. I
wanted to make the
> guide easy to follow, so I'd like to have a separate
format/style
> differentiating between a typed command, the output of
a command, and
> the contents of a configuration file - these seemed the
most common
> choices for manual administration.
> 
> To move technical info (config files etc..) into the
wiki takes a large
> amount of time using wiki markup, and displaying
configuration files
> inside a table takes a fair bit to format, so it looks
similar to what
> the user is expecting to see. To make it simpler, html
- <PRE> tags work
> best, however the CSSs only provide one format/style
for <PRE> tags.

This is exactly why using the Wiki is not the best way to do
technical
documentation.  DocBook is far better suited, because there
are tags to
support all these different usages:

<para>
  Here's my explanatory text about what happens
  when you run the <command>foosetup</command>
  command.  First, the following screen appears:
</para>
<screen>
  <computeroutput>Your setup of foo
    is complete.</computeroutput>
</screen>
<para>
  Then you can add the following line to the
  <filename>/etc/foo</filename> file:
</para>
<screen>
  <userinput>BAR=1</userinput>
</screen>

The wiki has no good way of converting these elements once
they're
properly tagged with DocBook anyway.  When we move to Plone,
there may
be a one-for-one conversion from DocBook in our CVS
repository to the
document in Plone -- or Plone might simply use the DocBook
XML "live,"
converting user editing as necessary.  I've no idea,
unfortunately.

For now, simply use the technical terms and you'll have to
rely on an
editor to tag your guide correctly with DocBook -- or you
could try
doing it yourself, using some of the starter information I
posted the
other day in our inaugural Munch 'N' Learn:

http://www.redhat.com/archives/fedora-d
ocs-list/2006-August/msg00081.html

DocBook is really very easy -- as easy as doing HTML or any
other markup
-- once you get started.  Most people only ever use a
handful of tags,
and add more to their "personal knowledge base"
as needed.  XML is
becoming (has become!) so widespread that it's almost
criminal *not* to
learn about it, and DocBook is just a specific type of XML
document.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937
BD11 3717
       Fedora Project Board: http://fedoraproj
ect.org/wiki/Board
    Fedora Docs Project:  http://fedo
raproject.org/wiki/DocsProject
-- 
fedora-docs-list mailing list
fedora-docs-listredhat.com
To unsubscribe: 
https://www.redhat.com/mailman/listinfo/fedora-docs-list