LiteratePrograms:How to write an article
From LiteratePrograms
- Note: this page is about writing literate programs on this wiki, not general English writing.
LiteratePrograms articles are easy to create, and easy to write. The basic markup is essentially the same as that used on Wikipedia, but with a few additional features that we describe below.
You can try out the markup described here at the Sandbox, a page for experimental test edits — you can't hurt anything, so please just give it a shot.
Contents |
LiteratePrograms markup and extensions
Almost all of the markup used on LiteratePrograms is exactly the same as on any other website based on the MediaWiki software. There is a detailed description of this markup on Wikipedia. The main difference between LiteratePrograms and the standard MediaWiki markup is that, on LiteratePrograms, we've added a special <codeblock> tag with several important abilities (which are described below). If you want to try any of this out, visit the Sandbox, a scratch pad article for experimentation.
Noweb embedded code syntax
The <codeblock> tag provides several useful features. First, by specifying a language as in <codeblock language=c>, you can get syntax highlighting. Although the list of supported languages for syntax highlighting is constantly expanding, here are some of them:
- ada, ada95, awk, c, c++, delphi, gpasm, groff, haskell, html, java, javascript, js, lisp, m4, make, makefile, matlab, occam, pas, pascal, patch, perl, plain, pov, povray, python, ruby, sh, scheme, shellscript, sql
Note that some languages like "c++" have to be placed in quotes. If you use a language which is not yet supported, your text will render without syntax highlighting. However, it's recommended that you still specify a language as it may be added in the future.
More importantly, you can use the syntax of the noweb literate programming tool inside these blocks to describe chunks of code. When the reader clicks the "download code" tab, the noweb tool automatically assembles these chunks into source files for viewing and downloading.
Note that the "code" tab is only available on articles in the main namespace; articles prefixed by "Category:", "LiteratePrograms:", "Talk:", and so on will not have this option. This is intentional, since these other pages are not intended to contain code.
The noweb syntax is very simple. Each segment or "chunk" of code is given a name, placed between double angle brackets:
<codeblock> <<name of this segment>>= some code here </codeblock>
It's important to have no space between the >> and the =. You can embed these code segments inside other code segments:
<codeblock> <<bigger segment>>= some code here <<smaller segment>> some more code here </codeblock>
You can create a chunk and add to it gradually over time just by using the same chunk name repeatedly:
<codeblock language=c> <<header files>>= #include <stdio.h> </codeblock> <codeblock language=c> <<header files>>= #include <stdlib.h> </codeblock>
If the segment name looks like a filename, a file will get generated for that segment:
<codeblock language=c>
<<blah.c>>=
int main() { return 0; }
</codeblock>
You can generate as many files as you like in each article. If you want to include "<<" or ">>" literally in code blocks, just make sure the "<<" is not at the beginning of a line. Don't use HTML entities; HTML entities in code segments are emitted literally in output files.
If the noweb input file generated from your article has a syntax error, the archive returned by "download code" will contain a "noweb.out" file giving the output of noweb to help you diagnose the problem, as well as the generated .nw file which is given as input. For some languages and environments, such as portable C or C++ programs, the server will even compile your program for you and show you any compiler errors or warnings.
If you haven't yet, go experiment with the syntax at the Sandbox. Then come back to learn about how to create and edit real articles.
Creating and editing articles
You don't even have to register to get started:
- To edit an article
- Just click the Edit tab at the top of the page while viewing the article.
- To create a new article
- Type the name of your new article in the search box on the left-hand side and click "Create/Edit".
What do I write?
If you're editing an existing article, your contributions may be as small as a simple spelling or grammar improvement, or they may consist of bug-fixes and additions to the code, expanded exposition, and completely new sections. Every little bit helps. If you're making major changes, it's often a good idea to post something about why you've made the changes on the article's Talk page (accessible by clicking the discussion tab). The talk page is also a good place to float new ideas you're unsure about, propose changes that might be controversial, and just generally discuss how to improve the article.
If you want to write a new article, and you're not sure what to write about, just browse around or visit LiteratePrograms:Categories requiring expansion and see if you can find a topic of interest to you missing an implementation in your favorite language. Then write it! It doesn't matter how bad, buggy, or incomplete your article is - we'll help to fix it up. If you are working on an article that's still under development, you can include the {{develop}} tag at the head of your article in order to make the unfinished state clear to other contributors.
But I don't know how to write a literate program
When talking to new potential users I often hear that they feel intimidated by the concept of literate programming and aren't quite sure how to do it properly. Our response to this is twofold:
- Literate programming is easy. Take a look at existing articles and emulate what they do. If you've ever described a piece of code to another person or written detailed documentation for code, you've done something very similar.
- Even if you don't want to write literate programs, that's okay! If you just dump some of your code on here, wrapped in <codeblock> tags, other volunteers will be glad to "literatize" it, adding explanations and rearranging for presentation. This is part of what makes wiki especially suitable for this project. You can also watch what we do with your code to learn about literate programming in a personal context. If you do just dump some code here, make sure to place a {{codedump}} tag at the top of the page (among other things, this will add your article to Category:Code dumps, so that other volunteers can find it easily).
Naming your article
LiteratePrograms doesn't really have any fixed conventions on naming articles yet, but here are a couple of guidelines:
- Articles belong in the main namespace, so don't prefix the name with Category:
- An example of a regular article is Merge sort (Scheme) — note the lack of a Category: prefix in the name.
- An example of a category is Category:Insertion sort — note that it doesn't contain any language-specific content, but does contain links to a bunch of language-specific articles
- Choose a name that (concisely) describes what your article is about
- Capitalize the first letter of the article name (this is a technical requirement on the part of MediaWiki)
- Include the name of the programming language used in your article in parentheses at the end of the article name
- Here are a couple of examples: Merge sort (Scheme), Singleton (Java), Sierpinski triangle (Haskell)
- If your article uses multiple languages, or can be compiled as valid code in multiple languages, list these divided by a slash in the name
- One example: Hello World (OCaml/F Sharp)
- If there are multiple articles on the same topic in the same language with different implementations, either merge them or distinguish them with an added word inside the parentheses
- Made-up example: Quicksort (C, procedural) versus Quicksort (C, functional)
Categorize your article
When creating a new article, be sure to add it to the relevant categories. Some of the top-level categories are listed on the LiteratePrograms:Welcome page, but try to dig down to the most specific category you can find - it may help to search for similar articles and see what categories they're in. Don't use multiple redundant categories, such as Category:Programming language:ML and Category:Programming language:Standard ML; just use the most specific one that is accurate and complete. Subcategories will ensure that your article is indirectly listed under all relevant categories.
Subject-area category tags
By default, category pages list the articles they contain in alphabetical order, separated out by the first letter of the article name. Since articles in the same subject-area category tend to have names that all start with the same letter (e.g. Quicksort (C), Quicksort (Eiffel), and Quicksort (Haskell) all start with "Q"), these articles will all get listed under the same letter ("Q" for "Quicksort" in the case of our example) on the corresponding subject-area category page. The result would look something like this:
Q
Although this isn't a critical problem, it can make subject-area category pages harder to navigate, especially when there are a large number of articles in the category. Fortunately, there is a solution to this problem! When adding a subject-area category tag to your article, place a vertical bar after the category name, and then add the name of the programming language used in the article. For example, if you wrote an article describing an implementation of the Quicksort algorithm in Eiffel, instead of using the category tag
- [[Category:Quicksort]]
you would use the tag
- [[Category:Quicksort| Eiffel]]
Adding the language name in this way ensures that the corresponding category page separates out its articles alphabetically by language name instead of article name (see Category:Quicksort for an example), making the category page much easier to navigate.
I still have more questions
If there's something you're still not sure about, or you have ideas, suggestions, or complaints, please feel free to ask about it either at the public forum or on the owner's discussion page. You can also e-mail the owner.