1 - Introduction1.1 - What is This?This is the user's guide for wtfm.(e/n #1) wtfm itself is a completely free, open-source documentation system that runs under Python 2.7, on a web server. You interact with it using a web browser. It manages documentation by project and page, and is capable of dealing with from one to many projects, and also of sharing techniques and content between those projects. It can produce documents anywhere on the local machine, and is especially good at producing documents anywhere on the web server where it resides. 1.2 - Is Any Python Resource Other Than Python 2.7 Needed?No. No non-standard import libraries are used. Everything required is in the wtfm repo. 1.3 - What Else is Required?A web server running under linux or MacOS. Basically, you need something that can run Python CGI in a *nix-compatible manner. Apache under Linux, for instance. You might be able to make wtfm work under Windows, but if you want to do that, I won't be able to be of much, or possibly any, help. 1.4 - What Problem does it Solve?wtfm's reason to exist is to massively power-up the process of creating documentation. Manuals, web sites, web-resident how-tos, textbooks, novels, etc. Really anything at all that you might author in text for further use with a markup language like HTML, markdown, and so on. Easy stuff has been made easy already by tools like markdown and Restructured Text. wtfm is here to keep the easy stuff easy, and make the difficult stuff easier, while seeing to it that you can arrange to never have to do any particular difficult thing more than once. 1.5 - How Did wtfm Come Into Existence?This project came into being because I needed a really powerful, to-the-metal capable tool to write documentation subject to as few limits as possible. Tools such as markdown and Restructured Text exist, but they're both very limited in what can be done. Raw HTML and CSS offer huge flexibility, but are incredibly cumbersome. The idea here is to have something that can do the most complex things easily, while being capable of anything HTML and CSS can do when used directly. Today, everything of real significance needs to be online. Software manuals, instructional texts, essays, news articles... you name it, it should be on the net. Blog publishing platforms make vanilla stuff easy; raw HTML and CSS make anything possible (and a royal headache to accomplish.) wtfm serves the technically-minded person who doesn't want to do more work than actually needs to be done, when the task at hand is serious documentation. And good grief, if something is challenging to do, surely we don't want to have to do it more than once! wtfm excels at letting you build up a working library of styles and techniques that you can apply very easily across projects. One project can even inherit another project's styles! In the end, wtfm can serve the reader very well, because you spend more time writing about what you need to be writing about, and less fighting the system. This inevitably leads to better documentation. The lack of limits, combined with the ability to document almost as fast as you can write was, for me at least, the "holy grail" of documentation. Not everyone writes. Of those who do write, most can write casually. wtfm really isn't aimed at them. Which is fine. This is the "Tactical Swiss Army Knife, Combat Edition, Nuclear, Unshielded" of documentation tools. It's primarily aimed at more difficult documentation tasks. Of course, it makes easy tasks even easier, too, so there's that. What do I mean by more difficult documentation? Well, for example, I had to write this manual. I actually wrote both aa_macro and wtfm specifically to have the tools I needed to write documents like that one, so I could avoid having to do it by hand. Having done so, I've done a lot of other work with, and development of, these tools as well. But that was the catalyst. 1.6 - What Will You Need?You need a working installation of Python 2.7-ish vintage. You need a web server. OS X has one. Anyone running a server has one. linux has one (many!) Windows might even have one, and if it does, it might even work properly with Python. Windows is still around, right? Hello? There are just a few Python and other files to copy into the webserver's CGI directories, and you will need to set the permissions for these. There's a very simple configuration file to set up. You will need to understand the directory structure of your web server. It's important to have a good handle on security if your web server is exposed to the network at large. That's it. If you think you can get all that handled, by all means, read on. 1.7 - For Online Documentationwtfm's primary target is the generation of online documentation. Towards that end, I have provided some preset style includes and example styles that can be used to immediately begin writing your documentation and have it come out in a usable, although basic in the visual sense, form. That certainly doesn't mean you couldn't use wtfm for other things, such as generate websites, manuals for printing, etc — you absolutely can (and I have. The entirety of OurTimeLines.com, for instance.) Even with wtfm being aimed at HTML, being able to generate any other markup language — even multiple markup languages from the same document source — is a side-effect that derives from wtfm being ridiculously powerful. In the spirit of "eating my own dog food", the provided includes and example styles are what I'm using to create this manual. The following features are readily available when using these includes:
You can enable and disable any combination of these features with a single line in your project. At some point, you will probably be interested in changing the look of some of these styles, or even writing your own; you can copy the includes and change them all you want. I don't recommend changing the actual includes I supply, as making a copy and using it instead of the ones I supply is trivial, and gives you something to fall back on if you have the need. 1.8 - Document NavigationWhen browsing this manual, as long as the main browser window is in focus, you can press the comma and period keys to go to the previous and next pages respectively. In addition, you can press the "t" key to go to the table of contents, and the "i" key to go to the index. There's a reminder of this at the bottom of every page. 1.9 - wtfm Style ConventionsAlthough this isn't an aa_macro manual by any means, I still spend a lot of time showing its use. So I do it somewhat formally, in order to (hopefully) impart maximum clarity. I do it, interestingly enough, using aa_macro's ability to pretty-print its own syntax and HTML/CSS syntax. Built-ins: [keyword parameters content]
Styles: {name content}
1.10 - Pure HTML Files Are Fastwtfm produces (or at least, I make it produce) pure HTML files. They're flat, there are no other files for the webserver to fetch, and there's no buried active scripting that is vulnerable to attack. This means the webserver can deliver a large numbers of pages close to one another in time before being seriously loaded. So the documents I produce are fast, relatively secure, and easily managed all in one place. They're also pretty portable. Everything is in one database and I can move that to a new server, point at the directories I want to use, hit generate, and wham, the site is back up. There's a lot more to be said for simplicity. I'd say it, but... 1.11 - Can't Find What You Need?Try the index. Try the table of contents. Still not able to find whatever it is? Contact me. There's a good chance what you want to do can be done; and if it can't there's also a chance I'd be willing to add the capability. It isn't unheard of for me to implement a new feature within hours of being asked for it. 1.12 - The Target AudienceAs you'll find out as soon as you try to get tricky, with great power comes great demands on you. This isn't your grandfather's authoring system.(f/n #1) So if you're looking for something easy, perhaps wtfm isn't for you. On the other hand, if you're feeling determined and think you would be able to really use this if you could only get it going, contact me. 1.13 - Just a little Friendly AdviceWhen you start out, create content and styles one bit at a time, then generate to test your work. Just like programming, it's a lot easier to figure out what you've done wrong when only one small change has been made. As you gain experience, you'll be able to do more and more, confidently, and you'll recognize your errors more quickly. 1.14 - And...Back up the database file regularly. I keep a month's worth of daily-staged changes. It's already saved me more than once. Backups. It's what's for ulcer-prevention.1.15 - One More ThingI have a terrible sense of humor. And a terrible sense of when it should be used. Or shouldn't. I would like to apologize in advance for any abuse of your funny bone.
Keyboard Navigation
, Previous Page . Next Page t TOC i Index
|
