h1 in Wiki

[Karsten Wade]

I've lost track of what we want to appear as a primary header (h1) on a
Wiki page.  That is, we sometimes use this:

{{{#!html
<h2>Page Title</h2>}}}

Is this strictly for visual affect?

In the case of the Docs/Beats, I think we need to stick to a strict
usage of each page having only one h1 and all other content being a sub:

= Page Title =

== A Section ==

=== Sub-section A ===

=== Sub-section B ===

== Another Section ==

According to this page:

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

... that is our method.

Seem reasonable?

- Karsten
-- 
Karsten Wade, RHCE, 108 Editor    ^     Fedora Documentation Project 
 Sr. Developer Relations Mgr.     |  fedoraproject.org/wiki/DocsProject
   quaid.108.redhat.com           |          gpg key: AD0E0C41
////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

[Paulo Santos]

Karsten,

If i'm not mistaken the = h1 = or even ==h2 == didn't work well in the
previous version of Moin.
Right now that should be fixed, so yes, i think you guys should follow the
guidelines already defined by FDP.


Paulo

On 3/2/07, Karsten Wade <kwade(a)redhat.com&gt; wrote:
>  I've lost track of what we want to appear as a primary header (h1) on a
>  Wiki page.  That is, we sometimes use this:
>
>  {{{#!html
>  <h2>Page Title</h2>}}}
>
>  Is this strictly for visual affect?
>
>  In the case of the Docs/Beats, I think we need to stick to a strict
>  usage of each page having only one h1 and all other content being a sub:
>
>  = Page Title =
>
>  == A Section ==
>
>  === Sub-section A ===
>
>  === Sub-section B ===
>
>  == Another Section ==
>
>  According to this page:
>
>  http://fedoraproject.org/wiki/DocsProject/WritingUsingTheWiki
>
>  ... that is our method.
>
>  Seem reasonable?
>
>  - 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-list(a)redhat.com
>  To unsubscribe:
>  https://www.redhat.com/mailman/listinfo/fedora-docs-list
>
>

[Dimitris Glezos]

O/H Karsten Wade έγραψε:
>  I've lost track of what we want to appear as a primary header
> (h1) on a
>  Wiki page.  That is, we sometimes use this:
>  
>  {{{#!html
>  <h2>Page Title</h2>}}}
>  
>  Is this strictly for visual affect? 
The above is the same as `== Page Title ==`, so we could just strip the
obfuscation and use the syntax.

After `<title>`, `<h1>` is the most important heading. On the wiki, I believe
the correct way to use it would be a title-style description of the page.
Something like a more decriptive of the pagename. For example:

  /DocsProject

has:

  = The Documentation Project =

In general, only one h1 should exist on a page, unless the page contents are so
disorganized that cannot fit under one category. This does not apply to our wiki
though (we just split the page in two if this happens).

>  In the case of the Docs/Beats, I think we need to stick to a strict
>  usage of each page having only one h1 and all other content being a sub:
>  
>  = Page Title =
>  
>  == A Section ==
>  ... 
Correct.

The way I see best a wiki page to be structured is shown below. Of course, Beats
don't have a TOC or breadcrumbs.

>  You are here:  Home >  Foo >  Bar<
>  
>  = Page title similar to page name =
>  
>  Some text describing the page. No more than 3 paragraphs, no less than one.
>  
>  [TableOfContents]
>  
>  == Foo section ==
>  
>  Text that describes/introduces the content of Foo section.
>  
>  === Subsection ===
>  
>  ...
>
>  ----
>  CategoryFoo 


-d


-- 
Dimitris Glezos
Jabber ID: glezos(a)jabber.org, GPG: 0xA5A04C3B
http://dimitris.glezos.com/

"He who gives up functionality for ease of use
loses both and deserves neither." (Anonymous)
--

[Paul W. Frields]

On Fri, 2007-03-02 at 15:33 +0000, Dimitris Glezos wrote:
>  O/H Karsten Wade έγραψε:
>  > I've lost track of what we want to appear as a primary header (h1) on a
>  > Wiki page.  That is, we sometimes use this:
>  > 
>  > {{{#!html
>  > <h2>Page Title</h2>}}}
>  > 
>  > Is this strictly for visual affect?
>  
>  The above is the same as `== Page Title ==`, so we could just strip the
>  obfuscation and use the syntax. 
It's not necessarily obfuscation -- the point is not the appearance, but
rather how it gets converted to DocBook.  To find out the effects, try
converting a Beats page to DocBook and see how the sectioning using '=',
'==', etc. changes the resulting markup.  The end goal in converting the
Beats is for each Beat to be a file containing a top-level <section>,
all of which are XIncludes in the parent <article> file.

Before we declare a standard here, check to see what it implies for the
conversion process and how much more editing is required to get the
resulting file in shape for publication.  I remember having to deal with
this several times, and unfortunately I took crappy (meaning "no") notes
on the right and wrong ways of doing this.

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
      Fedora Project:  http://fedoraproject.org/wiki/PaulWFrields
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug