Difference between revisions of "PC-BSD Wiki talk:Style Guidelines"

From PC-BSD Wiki
Jump to: navigation, search
(Additional Resources)
(The 'r' template)
 
(21 intermediate revisions by 3 users not shown)
Line 73: Line 73:
 
--[[User:Vater|Rg]] 07:26, 7 August 2012 (PDT)
 
--[[User:Vater|Rg]] 07:26, 7 August 2012 (PDT)
  
I don't always understand every edit Dru makes, and some I disagree with but I let them slide- although I usually fix the 'here' links.  I agree with having a heading for 'Other Resources' or 'Additional Resources' on the KDE page, since the two links get kind of lost there and seem to merge with the last lines of the instruction portion. One possible solution that would negate the heading is related to the cite extension. Have you looked on wikipedia and seen their list of links on the bottom of the page, some of the content there is not within the text. If i can figure out how to blend it with our current citelink and refheading stuff, and make a slightly different template for the 'citelink' situation. It may be that because we have the references heading, the 'Additional Resources' heading is "too much".
+
It may be that because we have the references heading, the 'Additional Resources' heading is "too much".
 +
 
 +
I don't always understand every edit Dru makes, and some I disagree with but I let them slide- although I usually fix the 'here' links.  I agree with having a heading for 'Other Resources' or 'Additional Resources' on the KDE page, since the two links get kind of lost there and seem to merge with the last lines of the instruction portion. One possible solution that would negate the heading is related to the cite extension. Have you looked on wikipedia and seen their list of links on the bottom of the page? Some of the content there is not within the text. If i can figure out how to blend it with our current citelink and refheading stuff, and make a slightly different template for this new 'citelink' type situation, it likely would be the best answer.
  
 
--[[User:Tigersharke|Tigersharke]] 23:55, 7 August 2012 (PDT)
 
--[[User:Tigersharke|Tigersharke]] 23:55, 7 August 2012 (PDT)
 +
 +
I guess that perhaps in general we can scrap the 'additional resources' within the handbook, but for other pages it would be fine. I tried to allow other text within the 'refernces' section, which can be done, but if it includes an external link, we are back to the same problem(s). I also looked at how 'good stub' may relate to new page creation. I think it is okay, since initial pages get heavily modified after the first edit or two that introduce the new content. Its good to have some sort of format for initial page creation.
 +
 +
--[[User:Tigersharke|Tigersharke]] 21:54, 8 August 2012 (PDT)
 +
 +
== Desktop pages ==
 +
 +
It appears that there is somewhat of a theme for how such pages should be constructed as a minimum. Screenshot of default (right after first install as the only desktop), description of how to reach the AppCafe{{r}} and other PC-BSD utilities (may include screen captures), and links to information from the desktop authors.
 +
 +
I think that we should not simply say "and here are some links for further information.." I think we should give some basic configuration/setup information for each desktop, and *then* say "for further info.." but this 'further info' could be within the new 'citelink' type (described above in 'additional resources' that drops it into the 'references' section at the bottom.
 +
 +
--[[User:Tigersharke|Tigersharke]] 02:25, August 8, 2012‎ (PDT)
 +
 +
== What else? ==
 +
 +
I am curious whether anything else needs to be defined or if what we have now should be refined further. This is mostly a "Now what?" kind of question.
 +
 +
--[[user:Tigersharke|Tigersharke]]
 +
 +
=== of numbered lists ===
 +
 +
see also [[#needed markup for lists]]
 +
 +
<code><pre><nowiki>
 +
# Numbered lists are good<br>
 +
## very organized<br>
 +
## easy to follow
 +
</nowiki></pre></code>
 +
 +
; example: cutting a part of [[Creating an Automated Installation with pc-sysinstall]]
 +
 +
<code><pre><nowiki>
 +
To create a custom installation, perform the following steps:
 +
 +
1. Determine which variables you wish to customize.
 +
 +
2. Create a customized configuration.
 +
 +
3. Create a custom installation media.
 +
 +
These steps are discussed in more detail below.
 +
</nowiki></pre></code>
 +
 +
: my "suggestion for improvement" for this part
 +
<code><pre><nowiki>
 +
To create a custom installation, perform the following steps:
 +
# Determine which variables you wish to customize.<br>
 +
# Create a customized configuration.<br>
 +
# Create a custom installation media.
 +
These steps are discussed in more detail below.
 +
</nowiki></pre></code>
 +
 +
Is that right? Can anyone check this (for "To ensure that the PDF and EPUB versions format correctly, use a [[wikipedia:Hard return|hard enter]] between the items in a bulleted list." of [[PC-BSD Wiki:Style Guidelines#Bullets | section Bullets of the ''Style Guidelines'']]).
 +
 +
Can you create a example for that (maybe in a [[PC-BSD Wiki:Style Guidelines#numbered lists | section ''numbered lists'']])?
 +
 +
Thanks for (all of) your work :-) :-*
 +
 +
--[[User:Vater|Rg]] 17:28, 19 August 2012 (PDT)
 +
 +
== The 'r' template ==
 +
 +
There may be instances where the original use of the <nowiki>{{r}}</nowiki> is sorta broken- specifically where it is in a link. I changed the template to cause a reduced font size, and this breaks links since the substitution (transclusion) is a bit more complex than one circled 'R' character. I also added to the style guideline, that the template for the 'r' should be used. Prior to changing the 'r' template, I inserted <span> tags around the 'circled R' character, I may have missed switching some of those to use the revised 'r' template.
 +
 +
I am considering another template to restore the former simple character substitution- who knows what the special key combo causes that character? :) In which case I think it will be template:rm for 'registered mark'
 +
 +
Whoops. I should have mentioned this here also: template:RM exists for the above need.
 +
 +
== ''superuser'' vs. ''root'' ==
 +
 +
[[User:Purgatori|Purgatori]] [http://wiki.pcbsd.org/index.php?title=Using_AppCafe%C2%AE&curid=266&diff=17163&oldid=16896 changed ''superuser password'' to ''root password'']. :-/
 +
 +
Does anyone can create a rule for that? After that we have to [http://wiki.pcbsd.org/index.php?title=Special:Search&redirs=1&ns0=1&search=superuser&limit=500&offset=0 search for the word ''superuser''] and change them.
 +
 +
<!-- i have no time (at the moment) -->--[[User:Vater|Rg]] 11:04, 22 October 2012 (PDT)
 +
 +
<!-- The instance where I changed "superuser" to "root" was one in which it may not have been clear to the reader that "root" and "superuser" are synonymous terms. I don't necessarily think that every occurrence of "superuser" needs to be changed, so long as what this term signifies is clear to the reader. [[User:Purgatori|Purgatori]]--!>
 +
<!-- Thank for that message (opinion). :-) If you want to, you can delete this section. [[user:vater|vater]] -->
 +
 +
<!-- BTW folks, we three tend to be the primary/active overseers of style guidelines on the wiki. We can decide individually or as a group which rules to add. Where discussion is needed, it will occur hopefully in a timely manner. :) -->
 +
 +
== list for same phrases ==
 +
 +
[[User:Drulavigne|Drulavigne]] [http://wiki.pcbsd.org/index.php?title=Using_AppCafe%C2%AE&curid=266&diff=17316&oldid=17163 changed PBI's to PBIs].<!-- All right! --> Can we create a list of stuff (standards) like that? Maybe it could be part of [[PC-BSD Wiki:Style Guidelines#Language usage and word choice | the section  ''Language usage and word choice'']].
 +
 +
--[[User:Vater|Rg]] 09:30, 9 November 2012 (PST)
 +
 +
: BTW: Please check up all uses of the word [http://wiki.pcbsd.org/index.php?title=Special%3ASearch&search=PBI%27s&go=Go PBI's]<!-- my english is to bad for that. (and in german genitive case can end with a "'s". :-/ ) --> and change them, if that is needful.
 +
 +
: --[[User:Vater|Rg]] 09:47, 9 November 2012 (PST)
 +
 +
== its ==
 +
 +
Salvete!
 +
 +
In my way of understanding<!-- greeting to my English-teachers --> ''its'' is also a phrase that must be replaced ([[PC-BSD Wiki:Style Guidelines#Language usage and word choice | section ''Language usage and word choice'']]) with ''it is'', or not?
 +
 +
--[[User:Vater|Rg]] 16:12, 3 December 2012 (PST)
 +
 +
No. This is one of those confusing English things that I personally feel is backwards to common sense. The contraction: it's equates to "it is" while the word "its" is the possessive meaning ownership by it. Our replacement guidelines for contractions should include the contraction: it's to be replaced by "it is" as you suggest. I hope this adds clarity.
 +
 +
--[[User:Tigersharke|Tigersharke]] 20:22, 14 January 2013 (PST)
 +
 +
== commandline examples ==
 +
 +
Just to let you know that I updated the decision on this to be in favor of substitution of a template enclosure for preceding lines with a space- this is treated by mediawiki as to place within an imperfectly dashed-box boundary. The template:txtbox is a significant improvement but it has one caveat right now: formatting needs to be added, such as line breaks, tabstops and similar.
 +
 +
--[[User:Tigersharke|Tigersharke]] 20:26, 14 January 2013 (PST)

Latest revision as of 20:31, 14 January 2013

This page may eventually get so large that it might need to be refined. It should eventually be used to create some examples, like the stub page, to partially replace some of the content here.

Perhaps a specialized template that could be called, which automatically highlights within its content, the portions referenced as examples. In this way, the example page could be extremely inclusive with built-in context to help clarify. This is starting to sound like a very cool idea. :)

Contents

[edit] needed markup for lists

Once ("official") again:

Style Guidelines (of our PC-BSD Wiki) are telling for lists, that we need a hard enter to ensure that the PDF and EPUB versions format correctly.

Does this count only for "unordered" lists? A change for a numbered list does not include hard enters.

Does anyone can check the result of the PDF and EPUB versions for it? Probably it does not format correctly, because they are also items (like for normal bullet), or not?

Maybe a <br> at the end of every (without the last) item would help (enough). (BTW: I did such a change preliminary.)

Here my example (as an offer) for the section Bullets:

To ensure that the PDF and EPUB versions format correctly, use a additional [[wikipedia:Help:Wiki markup#Line breaks|<code><br></code>]] between the items in a list.

== Bullets ==

There are two types of bullets in use:
# A bulleted list which begins uppercase. Whether or not it ends in punctuation depends upon the size of the list. For example:<br>
#* the [[What's New in 9.1]] list uses sentences to describe the features so ends in a period. Use this type of list when the list includes a description large enough to warrant at least one sentence.<br>
#* the [[Minimum Hardware Requirements]] list uses few words per item. Since the individual items do not warrant a sentence, this type of list does not end in a period.<br>
# A  bulleted list which begins with bolded text (typically the name of a menu item). The bolded section is capitalized to match the name of the menu item and followed by a colon (:). The sentence following the colon begins lowercase and should be worded so that the bolded item is the beginning of the sentence. An example is:<br>
#: '''Size on Disk:''' indicates the amount of space being used by the jail.<br>
#:: In this example, the menu item appears as "Size on Disk" (mix of upper/lowercase), "indicates" is lowercase and is worded so that it reads as one sentence (including the name of the menu item). Because it is a sentence, it ends with a period.

"in terms of collegiality"

-- Rg 11:55, 12 July 2012 (PDT)

I think I would be open to most any formatting of the bullets/lists as long as it can be consistent among variations and for the range of formats (html, epub, pdf, etc) and whatever is easiest/simplest and/or does not add a significant amount of work/typing. I generally do not deal with conversion to epub or pdf, so I cannot really offer any suggestions for that, and my methods may differ compared to how others might convert to those formats.

--Tigersharke 01:19, 13 July 2012 (PDT)

After more thought and comparison, I chose to swap your bullets section as you formatted it, into the text of the guidelines. (I agree with the format and use of it)

--Tigersharke 02:46, 18 July 2012 (PDT)

[edit] Overall size of document

The style guidelines page is good so far, and helpful with its completeness, but I think it will better serve if it were more brief. This can be achieved by transferring the examples to a page that would include context for all such examples. Also, it would allow for multiple examples to be shown while the hinted example could be highlighted. This would be possible via 2-piece wiki page. a simple page that sources a template perhaps, with the call to the template at each link to the example. Each example in this contextual example page would be numbered so that calling the page link would cause the specific example highlighting. Of course this is all still a really cool concept which has not been fully explored as yet- but doesn't it sound amazing?!

--Tigersharke 02:48, 14 July 2012 (PDT)

[edit] Headings vs CSS

This is the one part of our style guidelines that seems abused the most, with regard to how things probably should be done, versus how they have been done. I believe there is some issue of final appearance via heading markup that is preferred over the proper way of using headers. Due to this, if the actual desired results might be defined, then the wiki css can be adjusted to match, rather than skipping header levels or other such divergence. We may be stuck enforcing a non-standard heading formula if the CSS format is not determined or not switched in a timely manner.

--Tigersharke 02:59, 18 July 2012 (PDT)

[edit] Representation of dates and times

Maybe we should doing also wikipedia:ISO 8601 usage? :-/

--Rg 08:54, 1 August 2012 (PDT)

I think the built-in {{#dateformat:01 May 2012}} is about the best we can do, until the wiki software itself better conforms to ISO 8601. This was added to the style guidelines. A similar built-in for times could be used also, but I don't know where it is needed currently.

--Tigersharke 23:16, 1 August 2012 (PDT)

[edit] Additional Resources

In the article KDE4 the section title is removed. But what about PC-BSD for Linux Users#Additional Resources, PBI Manager#Additional Resources and other articles here?

Maybe it makes sense to create a "rule" in Style Guidelines.

--Rg 07:26, 7 August 2012 (PDT)

It may be that because we have the references heading, the 'Additional Resources' heading is "too much".

I don't always understand every edit Dru makes, and some I disagree with but I let them slide- although I usually fix the 'here' links. I agree with having a heading for 'Other Resources' or 'Additional Resources' on the KDE page, since the two links get kind of lost there and seem to merge with the last lines of the instruction portion. One possible solution that would negate the heading is related to the cite extension. Have you looked on wikipedia and seen their list of links on the bottom of the page? Some of the content there is not within the text. If i can figure out how to blend it with our current citelink and refheading stuff, and make a slightly different template for this new 'citelink' type situation, it likely would be the best answer.

--Tigersharke 23:55, 7 August 2012 (PDT)

I guess that perhaps in general we can scrap the 'additional resources' within the handbook, but for other pages it would be fine. I tried to allow other text within the 'refernces' section, which can be done, but if it includes an external link, we are back to the same problem(s). I also looked at how 'good stub' may relate to new page creation. I think it is okay, since initial pages get heavily modified after the first edit or two that introduce the new content. Its good to have some sort of format for initial page creation.

--Tigersharke 21:54, 8 August 2012 (PDT)

[edit] Desktop pages

It appears that there is somewhat of a theme for how such pages should be constructed as a minimum. Screenshot of default (right after first install as the only desktop), description of how to reach the AppCafe® and other PC-BSD utilities (may include screen captures), and links to information from the desktop authors.

I think that we should not simply say "and here are some links for further information.." I think we should give some basic configuration/setup information for each desktop, and *then* say "for further info.." but this 'further info' could be within the new 'citelink' type (described above in 'additional resources' that drops it into the 'references' section at the bottom.

--Tigersharke 02:25, August 8, 2012‎ (PDT)

[edit] What else?

I am curious whether anything else needs to be defined or if what we have now should be refined further. This is mostly a "Now what?" kind of question.

--Tigersharke

[edit] of numbered lists

see also #needed markup for lists

# Numbered lists are good<br>
## very organized<br>
## easy to follow
example
cutting a part of Creating an Automated Installation with pc-sysinstall
To create a custom installation, perform the following steps:

1. Determine which variables you wish to customize.

2. Create a customized configuration.

3. Create a custom installation media.

These steps are discussed in more detail below.
my "suggestion for improvement" for this part
To create a custom installation, perform the following steps:
# Determine which variables you wish to customize.<br>
# Create a customized configuration.<br>
# Create a custom installation media.
These steps are discussed in more detail below.

Is that right? Can anyone check this (for "To ensure that the PDF and EPUB versions format correctly, use a hard enter between the items in a bulleted list." of section Bullets of the Style Guidelines).

Can you create a example for that (maybe in a section numbered lists)?

Thanks for (all of) your work :-) :-*

--Rg 17:28, 19 August 2012 (PDT)

[edit] The 'r' template

There may be instances where the original use of the {{r}} is sorta broken- specifically where it is in a link. I changed the template to cause a reduced font size, and this breaks links since the substitution (transclusion) is a bit more complex than one circled 'R' character. I also added to the style guideline, that the template for the 'r' should be used. Prior to changing the 'r' template, I inserted tags around the 'circled R' character, I may have missed switching some of those to use the revised 'r' template.

I am considering another template to restore the former simple character substitution- who knows what the special key combo causes that character? :) In which case I think it will be template:rm for 'registered mark'

Whoops. I should have mentioned this here also: template:RM exists for the above need.

[edit] superuser vs. root

Purgatori changed superuser password to root password. :-/

Does anyone can create a rule for that? After that we have to search for the word superuser and change them.

--Rg 11:04, 22 October 2012 (PDT)


[edit] list for same phrases

Drulavigne changed PBI's to PBIs. Can we create a list of stuff (standards) like that? Maybe it could be part of the section Language usage and word choice.

--Rg 09:30, 9 November 2012 (PST)

BTW: Please check up all uses of the word PBI's and change them, if that is needful.
--Rg 09:47, 9 November 2012 (PST)

[edit] its

Salvete!

In my way of understanding its is also a phrase that must be replaced ( section Language usage and word choice) with it is, or not?

--Rg 16:12, 3 December 2012 (PST)

No. This is one of those confusing English things that I personally feel is backwards to common sense. The contraction: it's equates to "it is" while the word "its" is the possessive meaning ownership by it. Our replacement guidelines for contractions should include the contraction: it's to be replaced by "it is" as you suggest. I hope this adds clarity.

--Tigersharke 20:22, 14 January 2013 (PST)

[edit] commandline examples

Just to let you know that I updated the decision on this to be in favor of substitution of a template enclosure for preceding lines with a space- this is treated by mediawiki as to place within an imperfectly dashed-box boundary. The template:txtbox is a significant improvement but it has one caveat right now: formatting needs to be added, such as line breaks, tabstops and similar.

--Tigersharke 20:26, 14 January 2013 (PST)

Personal tools

Variants
Actions
Navigation
Toolbox