You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by Bob Harner <bo...@gmail.com> on 2010/11/30 04:11:02 UTC
Proposed wiki formatting guidelines
Everybody (particularly those editing the Confluence wiki),
Please see the new "Wiki Formatting Guidelines" that I've boldly invented at
https://cwiki.apache.org/confluence/display/TAPESTRY/Confluence+Site+Setup
Clearly I have no standing to propose any rules for the community, but
in my editing of some pages recently I have seen that Howard has
sometimes reversed some small changes that I have made, and I don't
want him to waste time doing so if I can get it right the first time.
So I wrote down some of what I think the formatting rules are or
should be. Feel free to correct or add to these in any way. My
instincts are generally to follow the proven Wikipedia guidelines in
most cases, but I realize that the Confluence export process present
some special needs.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: Proposed wiki formatting guidelines
Posted by Christophe Cordenier <ch...@gmail.com>.
You're right, this is kind of repeating...
Actually h1 should be in the header part of each page (top div), about the
content, maybe 'code less deliver more'
2010/12/3 Howard Lewis Ship <hl...@gmail.com>
> So you want the page title to appear twice, next to each other (once in the
> breadcrumbs, once as the h1. header)?
>
> On Thu, Dec 2, 2010 at 3:06 PM, Christophe Cordenier <
> christophe.cordenier@gmail.com> wrote:
>
> > Hi
> >
> > I tend to think that h1 stands for the title of the page. I think the
> > design
> > has been thought this way.
> >
> > Could we generalize this scheme ?
> >
> > h1 Title of the page
> >
> > Introductory text
> >
> > {ToC}
> >
> > h2 Section
> >
> > h3 Subsection
> >
> > ...
> >
> > Cheers
> >
> > 2010/12/1 Bob Harner <bo...@gmail.com>
> >
> > > Super, that's the list I was hoping for!
> > > On Nov 30, 2010 8:54 PM, "Howard Lewis Ship" <hl...@gmail.com> wrote:
> > > > I prefer the second.
> > > >
> > > >
> > > > A few other notes.
> > > >
> > > > Method and property names in code font: {{myProperty}},
> > {{someMethod()}}
> > > >
> > > > Class names (qualified or not) in default font.
> > > >
> > > > Path names in default font.
> > > >
> > > > First reference to a type on a page should be a link to
> > > > http://tapestry.apache.org/current/apidocs/... (or the component
> > > reference)
> > > >
> > > > @[AnnotationType|http://...AnnotationType.html]
> > > >
> > > > Use {code} for listings, not {noformat}.
> > > >
> > > > Use {noformat} for console output.
> > > >
> > > > Images and diagrams are small sized thumbnails, centered, no border.
> > > >
> > > > Page names a headings are All Words Captialized
> > > >
> > > > Treat the page title as if an h0. element, and put top level sections
> > > within
> > > > the page as h1. If the font size is too large we can fix that using
> CSS
> > > > rather than choosing a header level for visual size.
> > > >
> > > > I'm pretty sure I've been consistent about doing these things on the
> > > first
> > > > couple of pages of the tutorial.
> > > >
> > > >
> > > > On Tue, Nov 30, 2010 at 5:36 PM, Bob Harner <bo...@gmail.com>
> > wrote:
> > > >
> > > >> Style question: Which form of heading capitalization should we used?
> > > >>
> > > >> h2. All Words Capitalized
> > > >> or
> > > >> h2. Only the first word capitalized
> > > >>
> > > >> The old doc pages seemed to use the first, Wikipedia style
> guidelines
> > > >> require the second. Either is fine with me, but I'm seeing an
> > > >> inconsistent mix on the Tapestry pages so far.
> > > >>
> > > >>
> ---------------------------------------------------------------------
> > > >> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> > > >> For additional commands, e-mail: dev-help@tapestry.apache.org
> > > >>
> > > >>
> > > >
> > > >
> > > > --
> > > > Howard M. Lewis Ship
> > > >
> > > > Creator of Apache Tapestry
> > > >
> > > > The source for Tapestry training, mentoring and support. Contact me
> to
> > > learn
> > > > how I can get you up and productive in Tapestry fast!
> > > >
> > > > (971) 678-5210
> > > > http://howardlewisship.com
> > >
> >
> >
> >
> > --
> > Regards,
> > Christophe Cordenier.
> >
> > Committer on Apache Tapestry 5
> > Co-creator of wooki @wookicentral.com
> >
>
>
>
> --
> Howard M. Lewis Ship
>
> Creator of Apache Tapestry
>
> The source for Tapestry training, mentoring and support. Contact me to
> learn
> how I can get you up and productive in Tapestry fast!
>
> (971) 678-5210
> http://howardlewisship.com
>
--
Regards,
Christophe Cordenier.
Committer on Apache Tapestry 5
Co-creator of wooki @wookicentral.com
Re: Proposed wiki formatting guidelines
Posted by Howard Lewis Ship <hl...@gmail.com>.
So you want the page title to appear twice, next to each other (once in the
breadcrumbs, once as the h1. header)?
On Thu, Dec 2, 2010 at 3:06 PM, Christophe Cordenier <
christophe.cordenier@gmail.com> wrote:
> Hi
>
> I tend to think that h1 stands for the title of the page. I think the
> design
> has been thought this way.
>
> Could we generalize this scheme ?
>
> h1 Title of the page
>
> Introductory text
>
> {ToC}
>
> h2 Section
>
> h3 Subsection
>
> ...
>
> Cheers
>
> 2010/12/1 Bob Harner <bo...@gmail.com>
>
> > Super, that's the list I was hoping for!
> > On Nov 30, 2010 8:54 PM, "Howard Lewis Ship" <hl...@gmail.com> wrote:
> > > I prefer the second.
> > >
> > >
> > > A few other notes.
> > >
> > > Method and property names in code font: {{myProperty}},
> {{someMethod()}}
> > >
> > > Class names (qualified or not) in default font.
> > >
> > > Path names in default font.
> > >
> > > First reference to a type on a page should be a link to
> > > http://tapestry.apache.org/current/apidocs/... (or the component
> > reference)
> > >
> > > @[AnnotationType|http://...AnnotationType.html]
> > >
> > > Use {code} for listings, not {noformat}.
> > >
> > > Use {noformat} for console output.
> > >
> > > Images and diagrams are small sized thumbnails, centered, no border.
> > >
> > > Page names a headings are All Words Captialized
> > >
> > > Treat the page title as if an h0. element, and put top level sections
> > within
> > > the page as h1. If the font size is too large we can fix that using CSS
> > > rather than choosing a header level for visual size.
> > >
> > > I'm pretty sure I've been consistent about doing these things on the
> > first
> > > couple of pages of the tutorial.
> > >
> > >
> > > On Tue, Nov 30, 2010 at 5:36 PM, Bob Harner <bo...@gmail.com>
> wrote:
> > >
> > >> Style question: Which form of heading capitalization should we used?
> > >>
> > >> h2. All Words Capitalized
> > >> or
> > >> h2. Only the first word capitalized
> > >>
> > >> The old doc pages seemed to use the first, Wikipedia style guidelines
> > >> require the second. Either is fine with me, but I'm seeing an
> > >> inconsistent mix on the Tapestry pages so far.
> > >>
> > >> ---------------------------------------------------------------------
> > >> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> > >> For additional commands, e-mail: dev-help@tapestry.apache.org
> > >>
> > >>
> > >
> > >
> > > --
> > > Howard M. Lewis Ship
> > >
> > > Creator of Apache Tapestry
> > >
> > > The source for Tapestry training, mentoring and support. Contact me to
> > learn
> > > how I can get you up and productive in Tapestry fast!
> > >
> > > (971) 678-5210
> > > http://howardlewisship.com
> >
>
>
>
> --
> Regards,
> Christophe Cordenier.
>
> Committer on Apache Tapestry 5
> Co-creator of wooki @wookicentral.com
>
--
Howard M. Lewis Ship
Creator of Apache Tapestry
The source for Tapestry training, mentoring and support. Contact me to learn
how I can get you up and productive in Tapestry fast!
(971) 678-5210
http://howardlewisship.com
Re: Proposed wiki formatting guidelines
Posted by Christophe Cordenier <ch...@gmail.com>.
Hi
I tend to think that h1 stands for the title of the page. I think the design
has been thought this way.
Could we generalize this scheme ?
h1 Title of the page
Introductory text
{ToC}
h2 Section
h3 Subsection
...
Cheers
2010/12/1 Bob Harner <bo...@gmail.com>
> Super, that's the list I was hoping for!
> On Nov 30, 2010 8:54 PM, "Howard Lewis Ship" <hl...@gmail.com> wrote:
> > I prefer the second.
> >
> >
> > A few other notes.
> >
> > Method and property names in code font: {{myProperty}}, {{someMethod()}}
> >
> > Class names (qualified or not) in default font.
> >
> > Path names in default font.
> >
> > First reference to a type on a page should be a link to
> > http://tapestry.apache.org/current/apidocs/... (or the component
> reference)
> >
> > @[AnnotationType|http://...AnnotationType.html]
> >
> > Use {code} for listings, not {noformat}.
> >
> > Use {noformat} for console output.
> >
> > Images and diagrams are small sized thumbnails, centered, no border.
> >
> > Page names a headings are All Words Captialized
> >
> > Treat the page title as if an h0. element, and put top level sections
> within
> > the page as h1. If the font size is too large we can fix that using CSS
> > rather than choosing a header level for visual size.
> >
> > I'm pretty sure I've been consistent about doing these things on the
> first
> > couple of pages of the tutorial.
> >
> >
> > On Tue, Nov 30, 2010 at 5:36 PM, Bob Harner <bo...@gmail.com> wrote:
> >
> >> Style question: Which form of heading capitalization should we used?
> >>
> >> h2. All Words Capitalized
> >> or
> >> h2. Only the first word capitalized
> >>
> >> The old doc pages seemed to use the first, Wikipedia style guidelines
> >> require the second. Either is fine with me, but I'm seeing an
> >> inconsistent mix on the Tapestry pages so far.
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> >> For additional commands, e-mail: dev-help@tapestry.apache.org
> >>
> >>
> >
> >
> > --
> > Howard M. Lewis Ship
> >
> > Creator of Apache Tapestry
> >
> > The source for Tapestry training, mentoring and support. Contact me to
> learn
> > how I can get you up and productive in Tapestry fast!
> >
> > (971) 678-5210
> > http://howardlewisship.com
>
--
Regards,
Christophe Cordenier.
Committer on Apache Tapestry 5
Co-creator of wooki @wookicentral.com
Re: Proposed wiki formatting guidelines
Posted by Bob Harner <bo...@gmail.com>.
Super, that's the list I was hoping for!
On Nov 30, 2010 8:54 PM, "Howard Lewis Ship" <hl...@gmail.com> wrote:
> I prefer the second.
>
>
> A few other notes.
>
> Method and property names in code font: {{myProperty}}, {{someMethod()}}
>
> Class names (qualified or not) in default font.
>
> Path names in default font.
>
> First reference to a type on a page should be a link to
> http://tapestry.apache.org/current/apidocs/... (or the component
reference)
>
> @[AnnotationType|http://...AnnotationType.html]
>
> Use {code} for listings, not {noformat}.
>
> Use {noformat} for console output.
>
> Images and diagrams are small sized thumbnails, centered, no border.
>
> Page names a headings are All Words Captialized
>
> Treat the page title as if an h0. element, and put top level sections
within
> the page as h1. If the font size is too large we can fix that using CSS
> rather than choosing a header level for visual size.
>
> I'm pretty sure I've been consistent about doing these things on the first
> couple of pages of the tutorial.
>
>
> On Tue, Nov 30, 2010 at 5:36 PM, Bob Harner <bo...@gmail.com> wrote:
>
>> Style question: Which form of heading capitalization should we used?
>>
>> h2. All Words Capitalized
>> or
>> h2. Only the first word capitalized
>>
>> The old doc pages seemed to use the first, Wikipedia style guidelines
>> require the second. Either is fine with me, but I'm seeing an
>> inconsistent mix on the Tapestry pages so far.
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
>> For additional commands, e-mail: dev-help@tapestry.apache.org
>>
>>
>
>
> --
> Howard M. Lewis Ship
>
> Creator of Apache Tapestry
>
> The source for Tapestry training, mentoring and support. Contact me to
learn
> how I can get you up and productive in Tapestry fast!
>
> (971) 678-5210
> http://howardlewisship.com
Re: Proposed wiki formatting guidelines
Posted by Howard Lewis Ship <hl...@gmail.com>.
I prefer the second.
A few other notes.
Method and property names in code font: {{myProperty}}, {{someMethod()}}
Class names (qualified or not) in default font.
Path names in default font.
First reference to a type on a page should be a link to
http://tapestry.apache.org/current/apidocs/... (or the component reference)
@[AnnotationType|http://...AnnotationType.html]
Use {code} for listings, not {noformat}.
Use {noformat} for console output.
Images and diagrams are small sized thumbnails, centered, no border.
Page names a headings are All Words Captialized
Treat the page title as if an h0. element, and put top level sections within
the page as h1. If the font size is too large we can fix that using CSS
rather than choosing a header level for visual size.
I'm pretty sure I've been consistent about doing these things on the first
couple of pages of the tutorial.
On Tue, Nov 30, 2010 at 5:36 PM, Bob Harner <bo...@gmail.com> wrote:
> Style question: Which form of heading capitalization should we used?
>
> h2. All Words Capitalized
> or
> h2. Only the first word capitalized
>
> The old doc pages seemed to use the first, Wikipedia style guidelines
> require the second. Either is fine with me, but I'm seeing an
> inconsistent mix on the Tapestry pages so far.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: dev-help@tapestry.apache.org
>
>
--
Howard M. Lewis Ship
Creator of Apache Tapestry
The source for Tapestry training, mentoring and support. Contact me to learn
how I can get you up and productive in Tapestry fast!
(971) 678-5210
http://howardlewisship.com
Re: Proposed wiki formatting guidelines
Posted by Bob Harner <bo...@gmail.com>.
Style question: Which form of heading capitalization should we used?
h2. All Words Capitalized
or
h2. Only the first word capitalized
The old doc pages seemed to use the first, Wikipedia style guidelines
require the second. Either is fine with me, but I'm seeing an
inconsistent mix on the Tapestry pages so far.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: Proposed wiki formatting guidelines
Posted by Bob Harner <bo...@gmail.com>.
No, you weren't rude in the least! I hope it didn't sound that way. I'm
happy to follow any formatting style you want to go with.
On Nov 29, 2010 10:29 PM, "Howard Lewis Ship" <hl...@gmail.com> wrote:
> On Mon, Nov 29, 2010 at 7:11 PM, Bob Harner <bo...@gmail.com> wrote:
>
>> Everybody (particularly those editing the Confluence wiki),
>>
>> Please see the new "Wiki Formatting Guidelines" that I've boldly invented
>> at
>>
>>
>>
https://cwiki.apache.org/confluence/display/TAPESTRY/Confluence+Site+Setup
>>
>> Clearly I have no standing to propose any rules for the community, but
>> in my editing of some pages recently I have seen that Howard has
>> sometimes reversed some small changes that I have made, and I don't
>> want him to waste time doing so if I can get it right the first time.
>> So I wrote down some of what I think the formatting rules are or
>> should be. Feel free to correct or add to these in any way. My
>> instincts are generally to follow the proven Wikipedia guidelines in
>> most cases, but I realize that the Confluence export process present
>> some special needs.
>>
>
> Didn't mean to be rude about it.
>
> Should we discuss here, or in the comments on the page?
>
>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
>> For additional commands, e-mail: dev-help@tapestry.apache.org
>>
>>
>
>
> --
> Howard M. Lewis Ship
>
> Creator of Apache Tapestry
>
> The source for Tapestry training, mentoring and support. Contact me to
learn
> how I can get you up and productive in Tapestry fast!
>
> (971) 678-5210
> http://howardlewisship.com
Re: Proposed wiki formatting guidelines
Posted by Ulrich Stärk <ul...@spielviel.de>.
Here, please.
On 30.11.2010 04:28, Howard Lewis Ship wrote:
> On Mon, Nov 29, 2010 at 7:11 PM, Bob Harner<bo...@gmail.com> wrote:
>
>> Everybody (particularly those editing the Confluence wiki),
>>
>> Please see the new "Wiki Formatting Guidelines" that I've boldly invented
>> at
>>
>>
>> https://cwiki.apache.org/confluence/display/TAPESTRY/Confluence+Site+Setup
>>
>> Clearly I have no standing to propose any rules for the community, but
>> in my editing of some pages recently I have seen that Howard has
>> sometimes reversed some small changes that I have made, and I don't
>> want him to waste time doing so if I can get it right the first time.
>> So I wrote down some of what I think the formatting rules are or
>> should be. Feel free to correct or add to these in any way. My
>> instincts are generally to follow the proven Wikipedia guidelines in
>> most cases, but I realize that the Confluence export process present
>> some special needs.
>>
>
> Didn't mean to be rude about it.
>
> Should we discuss here, or in the comments on the page?
>
>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
>> For additional commands, e-mail: dev-help@tapestry.apache.org
>>
>>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
For additional commands, e-mail: dev-help@tapestry.apache.org
Re: Proposed wiki formatting guidelines
Posted by Howard Lewis Ship <hl...@gmail.com>.
On Mon, Nov 29, 2010 at 7:11 PM, Bob Harner <bo...@gmail.com> wrote:
> Everybody (particularly those editing the Confluence wiki),
>
> Please see the new "Wiki Formatting Guidelines" that I've boldly invented
> at
>
>
> https://cwiki.apache.org/confluence/display/TAPESTRY/Confluence+Site+Setup
>
> Clearly I have no standing to propose any rules for the community, but
> in my editing of some pages recently I have seen that Howard has
> sometimes reversed some small changes that I have made, and I don't
> want him to waste time doing so if I can get it right the first time.
> So I wrote down some of what I think the formatting rules are or
> should be. Feel free to correct or add to these in any way. My
> instincts are generally to follow the proven Wikipedia guidelines in
> most cases, but I realize that the Confluence export process present
> some special needs.
>
Didn't mean to be rude about it.
Should we discuss here, or in the comments on the page?
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@tapestry.apache.org
> For additional commands, e-mail: dev-help@tapestry.apache.org
>
>
--
Howard M. Lewis Ship
Creator of Apache Tapestry
The source for Tapestry training, mentoring and support. Contact me to learn
how I can get you up and productive in Tapestry fast!
(971) 678-5210
http://howardlewisship.com