OSDev.org

The Place to Start for Operating System Developers
It is currently Wed Jul 17, 2019 11:04 pm

All times are UTC - 6 hours




Post new topic Reply to topic  [ 50 posts ]  Go to page 1, 2, 3, 4  Next
Author Message
 Post subject:
PostPosted: Sat Dec 02, 2006 6:47 am 
Offline
Member
Member
User avatar

Joined: Wed Oct 18, 2006 3:45 am
Posts: 9284
Location: On the balcony, watching the Swedish Chef
Is there some manual of style? the notation of code blocks has gotten inconsistent and we better choose a style before we have to change half a wiki to a different style
For comparison: [wiki]Assembly[/wiki] and [wiki]CPUID[/wiki] (i prefer the first style)

_________________
"Certainly avoid yourself. He is a newbie and might not realize it. You'll hate his code deeply a few years down the road." - Sortie
[ My OS ] [ VDisk/SFS ]


Top
 Profile  
 
 Post subject:
PostPosted: Sat Dec 02, 2006 8:44 am 
Offline
Member
Member
User avatar

Joined: Sun Oct 24, 2004 11:00 pm
Posts: 127
Location: In my cube, like a good leming. ;-)
Combuster wrote:
Is there some manual of style? the notation of code blocks has gotten inconsistent and we better choose a style before we have to change half a wiki to a different style
For comparison: [wiki]Assembly[/wiki] and [wiki]CPUID[/wiki] (i prefer the first style)


Either style is OK with me, they're both readable, the content could use some help, but that is an entirely different story. ;-)


Top
 Profile  
 
 Post subject:
PostPosted: Sat Dec 02, 2006 5:46 pm 
Offline
Site Admin
User avatar

Joined: Wed Oct 20, 2004 10:46 pm
Posts: 665
Location: Texas
I like the 2nd because you can title each code block but it requires extra markup and Wikipedia uses the first so for those reasons I think we should use the first. We should probably add a Style section to [wiki]OSDevWiki:Editing[/wiki]

Edit: I think space in title names are fine where they are needed but why not just name the page A20?


Top
 Profile  
 
 Post subject:
PostPosted: Sat Dec 02, 2006 6:42 pm 
Offline

Joined: Sun Aug 06, 2006 2:19 am
Posts: 6
Oh my. Well, needless to say, I prefer the first.
Glad to be used as an example. :p


Top
 Profile  
 
 Post subject:
PostPosted: Sat Dec 02, 2006 8:16 pm 
Offline
Member
Member
User avatar

Joined: Tue Oct 17, 2006 9:29 pm
Posts: 2423
Location: Canada
FMota wrote:
Oh my. Well, needless to say, I prefer the first.
Glad to be used as an example. :p


Me too lol, I'm the one who added the Contents Box look to the Assembly article..

I thought it looked neat 8)

_________________
Image
Twitter: @canadianbryan. Award by smcerm, I stole it. Original was larger.
UNIX&BSD's, your only aspirations, to be imitated! 8)
Windows, are an opening in an otherwise solid and opaque surface through which light and, sometimes, even air can pass through; nothing more.


Top
 Profile  
 
 Post subject:
PostPosted: Sun Dec 03, 2006 3:35 am 
Offline
Member
Member
User avatar

Joined: Sun Nov 26, 2006 4:06 pm
Posts: 58
Location: Victoria, BC, Canada
NB: I am the author of the page and template used in the second example. Bias will likely be exerted.

I believe that ...
  1. Both styles need to be employed. Though the first style looks great and is easy to edit when only a few lines of code are involved, many (or at least I) find the code slightly hard to read when there isn't enough of a border between it and other text.
  2. Both styles need to use templates. Is has already been noted that setting a certain style now would provide a lot of tedious work if a different style was desired in the future. Templates, however, would allow editing a single page (ATM template:Code) to change the style for the entire wiki. Templates also allow for other neat features.
  3. If not completely removed template:Code needs to be fixed. Eugh! Look at that thing! Blue on grey! I was actually waiting for some style to develop before fixing the template. Hopefully we can establish a solution in this thread.


P.S. On an unrelated note could chase `chmod +w /var/httpd/www.osdev.org/mediawiki/images`, the image uploader is broken.


Top
 Profile  
 
 Post subject:
PostPosted: Sun Dec 03, 2006 9:28 am 
Offline
Member
Member
User avatar

Joined: Wed Oct 18, 2006 3:45 am
Posts: 9284
Location: On the balcony, watching the Swedish Chef
jhawthorn wrote:
Both styles need to be employed. Though the first style looks great and is easy to edit when only a few lines of code are involved, many (or at least I) find the code slightly hard to read when there isn't enough of a border between it and other text.


Current code snippets are already contained in a box with a different background color, and the only real difference is that you added a header to it. (invitiation for criticism 8) )

Quote:
If not completely removed template:Code needs to be fixed. Eugh! Look at that thing! Blue on grey! I was actually waiting for some style to develop before fixing the template. Hopefully we can establish a solution in this thread.

Suggestion: Since the majority prefers wiki's built-in style (maybe due to familiarity), could you change the template to look like the built-in style, but with header?

Still, if you want you can advertise some alternative templates, maybe you'll be lucky and we like it :)

Quote:
Both styles need to use templates. Is has already been noted that setting a certain style now would provide a lot of tedious work if a different style was desired in the future. Templates, however, would allow editing a single page (ATM template:Code) to change the style for the entire wiki. Templates also allow for other neat features.


If you provide a template:Snippet, i'm fine with it. I dont suppose chase wants to change the builtin wiki styles manually...

_________________
"Certainly avoid yourself. He is a newbie and might not realize it. You'll hate his code deeply a few years down the road." - Sortie
[ My OS ] [ VDisk/SFS ]


Top
 Profile  
 
 Post subject:
PostPosted: Sun Dec 03, 2006 2:27 pm 
Offline
Member
Member
User avatar

Joined: Sun Nov 26, 2006 4:06 pm
Posts: 58
Location: Victoria, BC, Canada
I have changed Style 2 to Style 1 via the template (including removing the header). If I create any more bearable templates for code I will make a post here before moving it into the main namespace.

While we're on the subject of style could I get some critiques on these SVGs I quickly made for the wiki? (Rendered as PNGs)

http://s138.photobucket.com/albums/q264 ... orn/osdev/


Top
 Profile  
 
 Post subject:
PostPosted: Sun Dec 03, 2006 4:10 pm 
Offline
Member
Member
User avatar

Joined: Wed Oct 18, 2006 3:45 am
Posts: 9284
Location: On the balcony, watching the Swedish Chef
Saw those images earlier on the wiki - Nice work.

i have some remarks about the contents though (micro/exokernel img)... ill be posting it on the wiki talkback pages shortly as its not really about style...

_________________
"Certainly avoid yourself. He is a newbie and might not realize it. You'll hate his code deeply a few years down the road." - Sortie
[ My OS ] [ VDisk/SFS ]


Top
 Profile  
 
 Post subject:
PostPosted: Thu Dec 07, 2006 3:28 pm 
Offline
Member
Member
User avatar

Joined: Mon Dec 04, 2006 6:06 am
Posts: 158
Location: Berlin, Germany
I think the style of article names should be something like this:
  • [wiki]Memory management[/wiki]. Plain article. Space used and no CamelCase.
  • [wiki]Global Descriptor Table[/wiki]. (just created that one) The name is often referred to as GDT. When articles are often referred by their abbreviation or is a techical term I think CamelCase can be justified. But a redirect should be created from Global descriptor table, and in this case GDT as well. This is to catch links from other articles and user searches.
  • [wiki]CPUID[/wiki]. An article about an assembly instruction. Should IMHO be all uppercase.
  • [wiki]DMA[/wiki]. An article with an abbreviation as name. Should be all uppercase. Should however redirect to the article named Direct Memory Access in my opinion.

Further all articles should start by shortly introducing the subject, like the [wiki]CPUID[/wiki] article.

It is a big job, but I'm not saying that articles should comply right now. It should only be some guidelines to follow when creating and editing pages. In time the wiki will have a more consistent style.

What do you think?


Top
 Profile  
 
 Post subject:
PostPosted: Thu Dec 07, 2006 5:59 pm 
Offline
Member
Member
User avatar

Joined: Wed Oct 18, 2006 3:45 am
Posts: 9284
Location: On the balcony, watching the Swedish Chef
Naming convention:
Agreed (I've been doing this all along so...)
Introduction:
Lot of work. Generally requires reorganizing/rewriting the page. Haven't done it for all pages.
However, some close-to-stub-like-pages dont need it - like several of the various file systems (they also easily fit into the screen). Still its pretty annoying to convert FAQ style of ordering to Wiki style of ordering. I'll try to do this from now on, but dont blame me if i miss it sometimes.
Redirects:
I preferrably use the common name, short or not. If you want a extra redirect, be my guest, but i doubt people looking up Interrupt Descriptor Table instead of IDT.
As a sidenote, is it useful to put all abbreviations in an separate catergory? - Gives people a lookup page automagically.
CamelCase:
since mediawiki suppports spaces properly, i think we can ban it. (ALL CAPS is a different story)

_________________
"Certainly avoid yourself. He is a newbie and might not realize it. You'll hate his code deeply a few years down the road." - Sortie
[ My OS ] [ VDisk/SFS ]


Top
 Profile  
 
 Post subject:
PostPosted: Fri Dec 08, 2006 12:00 pm 
Offline
Member
Member
User avatar

Joined: Tue Oct 17, 2006 11:33 pm
Posts: 3866
Location: Eindhoven
bcat wrote:
/me agrees.

DownWithCamelCase! :lol:


That just reminds me of the "Verein zur Behalt von dem Genitiv".


Top
 Profile  
 
 Post subject:
PostPosted: Fri Dec 08, 2006 4:19 pm 
Offline
Site Admin
User avatar

Joined: Wed Oct 20, 2004 10:46 pm
Posts: 665
Location: Texas
Candy wrote:
bcat wrote:
/me agrees.

DownWithCamelCase! :lol:


That just reminds me of the "Verein zur Behalt von dem Genitiv".

Guess it loses something in babelfish translation...

But yeah, CamelCase sucks. One of the reasons I picked mediawiki.


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 50 posts ]  Go to page 1, 2, 3, 4  Next

All times are UTC - 6 hours


Who is online

Users browsing this forum: No registered users and 2 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group