Help:Contents
From Fram
Contents |
How to edit an article the literate programming way
An important limitation: The code to be extracted to a file must be written in order,
but can be interspersed with explanation. A future version should allow arbitrary
placement using some kind of numbered id.
Literate programming is about explaining to human beings what we want a computer to do, so when you start a new article please do that right away, and then intersperse your text with the actual code. The example below illustrates how you would start a bit of coding in the Java programming language, but you can use Fram with any programming language you like.
You need to add an anchor above your code block, like this
{{#fileAnchor: helloworld.java}}
and then start your code block with syntax high-lighting this way
<source lang="java">
then add your code, and close the code block with
</source>
If you need another code block for the same file, use the same anchor as before, start a new code block, write some more code, and close it as you did the last time.
To concatenate the code pieces of a single file for download, you need to add a file link to your anchor, like this
{{#fileLink: helloworld.java}}
and to make it look pretty you use the inbuilt Mediawiki link mechanism:
[{{#fileLink: helloworld.java}} helloworld.java]
Questions and answers
I don't get it, please explain more clearly
Q: To be honest the whole concept of literate programming and especially its practical application in Fram still kinda goes over my head. Can you try to explain more clearly?
A: The code is extracted from the wiki article itself and given to you as a file with code you can use. This means anyone with access to Fram can improve the code, either by explaining it or by enhancing the code itself.
Just hit the download link in these articles to see what happens. :-)
Isn't this LaTeX?
Q: This concept is familiar - isn't this just the same concept as LaTeX?
A: Yes, it has just been adapted to the World Wide Web and the collaborative nature of a wiki. See the pre-history of Fram.
Security
You have several options to protect the confidentiality, integrity and availability of content aboard "Fram". Confidentiality is to ensure the privacy of sensitive information. Integrity is to ensure that information and programs are changed only in a specified and authorized manner; and availability is to ensure that "Fram" work promptly and that service is not denied to authorized users.
All activities have an element of risk, and "Fram" is no different. You should consider
- the assets to be protected
- the threats in the assets' environment,
- the vulnerabilities to these threats,
- the types of impact to be reduced, and
- the safeguards used to mitigate the risk.
Firstly, it makes little financial sense to protect something that is cheap to replace, unless the impact is severe. So before you go overboard and add all kinds of safeguards to your "Fram" instance, which will surely negatively impact the user experience and increase your administration costs, consider what information you have on board first. Secondly, consider what safeguards are already in place - audit of all pages with notification is built in, you can use access control, and you can authorize users or lock pages from changes from unauthorized users. If this is not enough in your situation, you can add several extensions to "Fram" for enhanced functionality.
- access-control is out of scope as there are already plenty extensions for it but the risk of trojan injection on a completely open repository is a risk to consider...
- move "Fram" in house and implement single-sign on using your regular access controls, like OpenLDAP or Microsoft Active Directory, so users don't have to remember multiple user account names or passwords.
- If your Fram is public but still requires users to sign in, you can consider OpenID: http://www.mediawiki.org/wiki/Extension:OpenID so they won't have to manage extra credentials specific to your project.
- Use SSL to encrypt traffic between your web server and the client.
Secure Programming for Linux and Unix HOWTO
In his book "Secure Programming for Linux and Unix HOWTO", David A. Wheeler writes
"...at least some of the people developing and reviewing the code must know how to write secure programs.
Hopefully the existence of this book will help. Clearly, it doesn't matter if there are "many eyeballs"
if none of the eyeballs know what to look for."
Please read Wheeler's book and make secure code a way of thinking when you write your own code. Perhaps literate programming can make this easier? If you explain what you are trying to do, think about security, and write your code in a literate programming style with Fram, then on review any flaws may be more readily apparent? For instance, you could link to relevant parts of Wheeler's text when you explain the security features of your code. Sounds reasonable to me, but only time will tell.
PHP security
Even though Mediawiki is at the heart of large sites like Wikipedia it is not flawless, and there are bugs in the core of the PHP interpreter itself. Since Fram is running at a hosting provider, we can't really do much about keeping PHP itself up-to-date. We try to keep up with security updates in Mediawiki - see Special:Version to check if we're coping. Fram itself is written in PHP, and though it at present is functionally limited though working, we are aware that it is low on error checking - so be warned, and use it at your own risk. Please use the Fram talk page to discuss problems in the Fram code, or even better - just fix the code and write an explanation in the article itself - that's the literate programming way. In a small effort to thwart vandals, we have disallowed anonymous editing.
Here is a list of resources in order of freshness, in the hope that you may find it useful:
- Daniel Egeberg wrote PHP Security in June 2008.
- The PHP Security Consortium wrote a great PHP security guide, but the web pages have not been updated since 2006, and some of the information may be too old.
- Pax Dickinson wrote Top 7 PHP Security Blunders in 2005
- Dave Clark wrote PHP Security Mistakes in 2004. Good information, but some of this information may also be too old.
- John Coggeshall wrote PHP Security, Part 1, PHP Security, Part 2, PHP Security, Part 3 in 2003.
Haskell
Haskell is a functional programming language, and is rather different from imperative languages like C. Hal Daum´e III has written Yet Another Haskell Tutorial, which I recommend as your first stop on your journey into Haskell. For beginners, he recommends getting The Glasgow Haskell Compiler - GHC for short, since it contains both a compiler and an interactive environment. The current stable release is GHC 6.10.1. To help ease C/Java programmers into Haskell, Eric Etheridge wrote the most helpfully entitled Haskell for C Programmers, which I recommend as your second port of call. Then I suggest you have a look at Arjan van IJzendoorn's Tour of the Haskell Syntax, and finally Ertugrul Söylemez article Understanding Haskell Monads. Haakon has written an Introduction to Haskell, which shows how you can intersperse source code with explanation using Fram, and then let Fram extract and concatenate the source code into downloadable files - ready to compile and run in GHCi.
