Jump to: navigation, search

Primary Copyright Licence

Some issues - I don't like the GFDL [there are certain problems like its
poorly worded DRM restrictions that have been the subject of some
controversy recently] and I think you should seriously consider this
instead of just using the GFDL because wikipedia does it [Sorry if this
isn't the reason, but it's what the combination of GFDL and mediawiki
brings to mind

[quoting User:Random832 in <slrne1s7sc.108a.random832@random.yi.org> on comp.lang.c 03:18, 20 Mar 2006 GMT]

Some possible scenarios for use of the wiki's (future) content:

  • to copy an individual page (in part or in whole) in text/html/wiki-text format for personal reference or for (possibly after modification) public redisplay elsewhere such as incorporation into another wiki
  • to copy the entire wiki for replication on an intra-net or as a public mirror
  • to copy parts for a text/html reference as part of the documentation for a (non-)commercial compiler.

The main thing that the GFDL achieves is in the last case to codify the ethical expectation that any commercial vendor, having benefited from our work, passes on a benefit to others by "sharing alike".

The DRM wording is unfortunate but according to RMS, not intended to apply to personal use, and in any case, not a major issue. --Netocrat 00:55, 21 March 2006 (UTC)

Secondary Licencing of Code

Second, there's no particular reason that code segments in an article
can't have their own license. [say, the GPL - which the GFDL is
incompatible with.]

(continuation of previous quote from User:Random832's post)

So let's rewrite:

Policy: Contributed code enters the public domain unless an alternate GFDL-compatible licence is specified at time of contribution
Contributed code enters the public domain unless the contributor specifies otherwise at time of contribution - i.e. in a following summary line as described below. Any alternative licence must be compatible with or equal to the GFDL.

as

Policy: A parallel licence may specified for non-trivial contributed code
Contributed code is licenced under the GFDL along with other content. A contributor can optionally specify a parallel licence at time of contribution - i.e. in a following summary line as described below. (it doesn't really make sense for this licence to be anything other than public domain or some form of open source licence)

--Netocrat 00:55, 21 March 2006 (UTC)

The Standard

Can text from the standard (or, more specifically, drafts of the standard), the rationale, and so forth be incorporated into the Wiki? What license does WG14 release their stuff under? Can they be contacted for permission? --Random832 02:34, 21 March 2006 (UTC)

It's not a public/open copyright. Normal 'fair use' rights apply - quotes need to be attributed. There are currently a few cases for string.h functions where the wording has been copied almost verbatim from the standard - they need to be reworded (the 'shall' convention Flash started seems to be a good one to follow) or properly attributed. --Netocrat 03:54, 21 March 2006 (UTC)

Ordering of sections for library reference

(Maybe there should be a separate Policies and Conventions page for each "wikiproject")

I think there should be a consistent and well-defined order for the sections of these pages. My proposal is these sections in this order

Prototype

"Usage" for macros, "Declaration" for extern data - says what header file(s) should be included, has the prototype, prototype-alike for function-like macros, or declaration for extern data in <c>. Analogous to "SYNOPSIS" in manpage

Description

What it does, etc. Self-explanatory, and most already have this.

Return value

Return values and, if applicable (in the context of the standard itself, mostly for math functions), errno setting.

Examples

Again, self-explanatory.

Implementation

For the code for the ongoing standard library implementation project

See also

Links to other on-wiki articles.

References

  • The Standard
  • FreeBSD online manpage
  • FAQ question
  • any other relevant references

--Random832 22:53, 21 March 2006 (UTC)


Yes, it's a good idea to have a template. How about we add a sub-category to Category:Guidelines for this Wiki - Category:Template Articles - where you could put this up as a template article with generic content? Don't make too many wholesale changes to existing pages before doing that - let's agree on a structure first. We could add per-sub-project guidelines as individual articles to Category:Guidelines for this Wiki. --Netocrat 23:11, 21 March 2006 (UTC)
I think that regardless of agreeing on other changes, the prototype section should be moved to above the other sections that refer to identifiers first named in the prototype section - that's just common sense. --Random832 23:36, 21 March 2006 (UTC)
That seems reasonable, but let's document the template first so that we can make all required changes to existing articles at the same time. --Netocrat 00:07, 22 March 2006 (UTC)

Multiple functions per page

What are everyone's thoughts on documenting multiple functions on one page, as I have done for Standard Streams and malloc? I think that it's a good policy to be able to have multiple related functions on one page and discuss issues relating to all of them at once without duplication, and in general to have more "meat" per page. Currently, this page is silent on the issue, what do you all think? (to clarify, I think that typical manpages should be a guide to this - i.e. document all ?printf functions on a single page, and all three of getc/fgetc/getchar on another; not all stdio functions on one page) --Random832 20:22, 23 March 2006 (UTC)

Redirects would of course be placed for each identifier to the page where it is documented. --Random832 20:24, 23 March 2006 (UTC)

I agree that multiple related functions on a page makes sense and that redirects are required for the other names. --Flash Gordon 20:47, 23 March 2006 (UTC)

There's a problem, that the other functions don't show up in the category list. If someone is looking in the category C library reference manual, they will not find any hint that we have documented realloc, calloc or free. They may not think to look under malloc. Ralmin 01:54, 24 March 2006 (UTC)

I had believed that redirects could be added to categories - apparently my edits are silently dropped. How about we have an actual index page of all the functions, and rely on whether the links are red or blue rather than whether the page appears in the category, to determine whether a function has been documented? --Random832 03:37, 24 March 2006 (UTC)

There are (at least) two technical solutions other than that. The first is to transclude the malloc article from each of realloc, free and calloc with this syntax: {{:malloc}}. Each article then appears in the category. The talk page and histories of all of the articles are distinct. Section edits can be made on any of the articles and are recorded in the malloc article's history.

The problems with this are that edits to the malloc article do not appear in any other article unless that other article is afterwards purged or edited and saved, and that section edits don't always work as expected. So cross that one off the list for now.

The second solution is identical except that the base article is made into a template (Template:Malloc) and the transclusion code looks like this: {{malloc}}. Works fine, but to me it's undesirable to have actual content in the template namespace.

Another non-technical solution is to separate the articles completely, which is cleaner but less friendly for the reader. We could deal with that by linking from all four articles to a brief "memory function usage" article in the C tutorial category. This also reduces the size of each individual article which is a handy side benefit. This is the approach that I advocate. --Netocrat 05:08, 24 March 2006 (UTC)

I think that we should have them all be on the one page, with redirects, and deal with the category problems in one of two ways: hack the code to allow redirects to be added to categories, or don't rely on the categories for end-user browsing. In other words, an index page should be created with links to all of the pages, and we should link to that index page prominently and downplay the use of the category listing for people who are "end-users" (i.e. just looking for information rather than editing the wiki) --Random832 00:21, 25 March 2006 (UTC)

This (along with capitalisation) is one area where MediaWiki is proving unwieldy. Yes, a hack like that would be one solution. Another solution is to manually list redirect pages on the category page; this is pretty clumsy though as they won't be included in the alphabetical listing. An index page is workable and we already have one - the standard header articles. i.e the implementation of string.h lists all of its contents and provides links to each. As for all-on-one-page, I don't have a problem with that as long as the article doesn't grow too huge. --Netocrat 00:54, 25 March 2006 (UTC)

To supplement what I've just written on Talk:Standard Library, let's drop the idea of using categories for general end-user navigation at least for now - they're too unwieldy in their current form - and use manual index pages as Random832 suggests. For library headers, we could simply have a comma-separated list at the top of the page listing the symbols defined/declared by the header and linking directly to the sub-page for each one. --Netocrat 15:34, 30 March 2006 (BST)

The new skin that I've put up screenshots of is partly inspired by this discussion. It replaces categories with the treeview and navigation bar, both of which support redirects as well as ordinary articles. --Netocrat 14:16, 22 April 2006 (BST)

Capitalisation

I've just updated the article and section titling conventions to specify all-lowercase where possible. In past email discussions with FlashGordon and dop we decided to follow this convention, and it's time to follow through on it. I've just written a script that will run through all pages in the main, planning and clc/project namespaces retitling section headings and articles according to this convention, and unless anyone objects or asks me to hold off on it, I'll shortly run it under the User:ImportBot account. The script ignores the content of talk pages and titles/content of pages in the K&R2 solutions section. --Netocrat 22:58, 28 March 2006 (BST)


Why do section titles have to be lowercase? I assume where these refer to identifiers that are in lowercase they already are, but why otherwise? Why wasn't this discussion open to the public? (Mainly, I'm interpreting your statement as requring the first letter of section headings to be in lowercase, since this is always possible, and this won't look good. I have no objection if you meant the first letter is to be uppercase) --Random832 02:10, 29 March 2006 (BST)

The wording I used above might have been ambiguous; it's clearer on the policy page - the first letter of section titles should be uppercase unless otherwise required (e.g. "comp.lang.c" or as you write, a lowercase identifier). As for public discussion - that's why I started this section. All suggestions are welcome - I've put this one up as a default since at least three of us agreed at least partly to it and I'm finding the capitalisation issue a consistent niggle that I'd like to have something definitive for. Next time I'll avoid editing the article before discussion in this talk page. --Netocrat 02:29, 29 March 2006 (BST)
I haven't run this script yet since the new skin that I'm working on will require a whole lot of retitlings that can occur at the same time if it's adopted.
--Netocrat 14:16, 22 April 2006 (BST)
The script's been run now that the Treeview skin is default; there are still manual changes to make and I'm progressing through them. I wrote above that I'll avoid editing the article before discussion, so here's a proposed rewording to the "Article and section titles" section:
Article titles and section headings should be as brief as possible without loss of meaning; a concisely-titled redirect page may be provided for articles with long titles when there's need for linkage from a Usenet post.
The title should use colons as a separation character so that the article slots into an appropriate part of the treeview hierarchy.
The first character of article titles (and of each colon-separated component) and section headings should be uppercase unless otherwise required, such as for function names that begin with a lowercase letter.
All remaining characters should lowercase except for any letters that require capitalisation, such as the "C" and "S" in "the C Standard", acronyms such as "ISO" and standard identifiers such as "FILE" or "INT_MAX".
For historical reasons template titles are all-lowercase; for consistency this practice should be continued.
--Netocrat 00:30, 27 June 2006 (BST)

Links to the Project namespace

The Project namespace has been renamed from 'Clc' to 'clc-wiki'; I've added the following text to the "Namespaces" section - I made it as an incidental change whilst recapitalising the page but it's subject to the same discussion as other changes:

Links to pages in the 'clc-wiki' namespace are better written as the more generic 'Project', to ease any future renaming of this namespace.

The rationale for using "Project" rather than "clc-wiki" is that if anyone objects to the renaming, it's simple to switch it back to "Clc" without any new links breaking.

Personal tools