Much of my work in TLDP relates to helping readers as well as authors, new as experienced alike. In this I propose a number of ideas, and in the spirit of show me the code! I have made a number of prototypes that have and hopefully will continue to be taken up at the official TLDP site. To simplify things I have collected all prototypes here.
All these are prototypes, meant for further refining; all comments are therefore welcome.
| Status: | Accepted |
This template is based on my Multi Disk HOWTO in that the headings were kept and only a little text retained and edited as example of contents. Like the orginal HOWTO itself this template is suitable for large HOWTOs. Have a look at the sample HTML file and then download the SGML file.
Note that the titles are examples only, do not consider this a straight jacket, only an example and also a check list of topics you might want to cover and an example of how to organise the material. Most likely you will edit this substantially.
| Status: | Accepted |
This template is based on the large template above where the contents has been trimmed down considerably as an example for smaller HOWTOs.
As above this is only an example, feel free to change things from this. Have a look at the resulting HTML file and then download the SGML file.
| Status: | Accepted |
Unfortunately the LDP archives are not very well know, not even that most distributions include a copy under /usr/doc/HOWTO/ for most distributions (using FSSTND) or /usr/share/doc/HOWTO/ for recent distributions (using FHS). I have therefore proposed including an intro(ldp) man page that will easily show up when using man -k <some keyword> when people are looking for more general help. The nroff source is also available.
This man page is now available in many distributions.
| Status: | Working Prototype. Superceeded by The LDP HOWTO Generator NG |
This is a tool made to overcome the initial problems of learning the tools and conventions used for writing documents for TLDP. It will help in making the first draft but as of yet it cannot be used for editing existing documents. The generated text together with sample source of the templates above will most likely be sufficient for further work.
This is an HTML file that renders on a web browser into a document with guiding texts and a number of forms for filling in heading, titles, contents and more as well as a fair amount of JavaScript that renders this into LinuxDoc SGML. The structure is again from the Large Template above but is easily changed to suit other HOWTOs: headings can be renamed, levels changed or removed. On clicking the button to compile the LinuxDoc SGML code is outputted into a text field, ready to be copied and pasted into a text file.
Note that this is self contained; it is not necessary to connect to a web server nor is it necessary to be on-line at all. Also the tool is validated as valid HTML 4.01 Transitional and has been tested using Netscape 6.2.1 as well as Internet Explorer.
The tool is verified using the whole LinuxDoc SGML tool chain. The generated SGML as well as the compiled HTML is available for viewing.
| Status: | Working prototype |
The report by Gerd Berget identified several potentials for improvement on organising the HOWTO collection and some of this has a definite impact on the HOWTO Generator too which lead to the development of The LDP HOWTO Generator NG. Some of the improvements are
In addition the JavaScript code will be reworked into something more elegant (or less embarassing) and use of CSS. In order to support low end configurations and maximise the user base only a limited set of JavaScript features will be used.
Code is now released for comments. Testing are positive in Mozilla 1.7.7, Firefox 1.04, Opera 8.01 and Internet Explorer 6.0 SP2 and the toolchain has been tested to end point.
Note that this is self contained; it is not necessary to connect to a web server nor is it necessary to be on-line at all. Also the tool is validated as valid HTML 4.01 Transitional and is using valid CSS
The Generator was tested using the WebXACT for quality, accessibility, and privacy issues. While the quality checks out fine the accessibility issues were not trivial. Much time and effort was spent attempting to gain approvement and while there are no priority 1 errors there are a number of errors and warnings that I could not fix without spending too much time reworking the Generator. I hope the effort spent has improved usability and accessibility. The privacy issues are strange. While the Generator does not submit the contents of its forms the WebXACT believes it does so, twice. I do not believe the issues raised are important but if anyone has a fix for any of these feel free to contact me.
In line with recent trends this Generator now contains built in test useful for regression testing. Pressing ALT-F or the button named Fill in fields for self test all fields will be filled in using a predefined set of texts. To avoid accidentally doing so the title field must be set to Selftester (case sensitive). Compiling to LinuxDoc SGML is done by pressing ALT-C or the button named Start Compiling the Form.
The extensive use of JavaScript has made the Generator flexible. For instance a total reworking of chapter titles, predefined texts or layout is quite simple.
The tool is verified using the whole LinuxDoc SGML tool chain using linuxdoc-tools (0.9.21). The generated SGML as well as the compiled HTML is available for viewing.
Worklog:
Lately this generator has attracted some interest on the net, some tracebacks:
| Status: | Working Prototype |
This proposal attempts to define file hierarchy and contents for organising LDP documents making it possible to integrate the document base and also refer to externally created documents. Latest issue is available here.
The idea is to make the directory structure for all documents for all languages logical and easily navigable using browsers as well as simple cd and ls. The LDP Collection Generator will have to be made compliant with this.
| Status: | Mockup only |
This is a tool made to overcome the problem of stale HOWTO collections on the net and also infrequent publishing elsewhere, for instance on cover disks supplied with some computer magazines.
This is an HTML file that renders on a web browser into a document with guiding texts and a number of buttons, check boxes and radio buttons that allows the reviewer to decide on what documents to compile into the new collection as well as the formats and, optionally, compression scheme used.
This generator has to be used in conjunction with an extensive backend on a server that houses the entire collection and is well connected to the net. A complete collection will be larger than 600 MB so the access to this tool might have to be restricted to avoid overloading.
TLDP maintains a large and growing collection of various documents, HOWTOs, Guides and magazines, that are frequently updated. This tool should make it simple to get the desired selection of the latest snapshot of the collection at any time.
| Status: | Working Prototype |
The markup used in writing HOWTOs can be used for far more than is done presently. This example shows how it is possible to use the markup for use with NetHelp, the help system used in earlier versions of Netscape browsers, to enable use of quick overview of table of contents as well as advanced keyword searching
NetHelp looks like a very useful platform for accessing and reading HOWTOs. I therefore made a test case by converting the Updated Mini-HOWTO into the NetHelp format. If you have Netscape Navigator you could try it out by first download the zip archive, read the readme file and unpack the files AND the directory in the NetHelp directory on your computer and then start with this URL. Note that you will need to turn on JavaScript to make it work.
| Status: | Samples only |
Not everyone knows of HOWTOs and therefore fail to locate valuable information even when these are installed on the disk. Many know of the kayword search functionality of man so the idea is to make stub man pages, one for every HOWTO that contains keywords to allow for searching and information on what HOWTO is appropriate and where it is located.
So doing
bash$ man -k diskshould give disk (ldp) as part of the output.
Once again the Multi Disk HOWTO come in handy as a test bench from which I made Multi Disk HOWTO(ldp) rendered as plain text from the nroff source.
| Status: | Working Prototype |
Currently there are two different types of tables of HOWTOs, one that is an itemised list of all HOWTOs sorted by name and one that is a tabular form with one entry per HOWTO with links for reading and downloading.
Feeling the latter was easier to read but still lacking in information I set out to make a more complete format that offers additional formats for reading and downloading, the abstract of each HOWTO along with keywords. Numerous searching schemes are possible but the simplest of them all is just to use the search function in the web browser so it is important to make each entry as complete and informative as possible. In addition each entry offers quick and accurate mailto-links for contacting author or TLDP with feedback.
In its current non.JavaScript driven form each entry takes about 2 KB which is in the high end of what I am aiming for. Given 450 HOWTOs plus guides and other documents this could be about 1 MB in size. A JavaScript version starts with an overhead of about 2 KB and 0.5 KB per entry. Also the vertical space for each entry is larger than I would like. It is however functional, please have a look:
| Status: | Working Prototype |
Web hit analysis is a good example of data reduction problem: too much reduction leading to less meaningful results and too little leading to information overload. Most analysis tools seem to err on the side of excessive reduction yielding information on number of hits per file. In order to better understand our readers a new tool was developed: the correlator. As the name implies it correlated web page from with the web page to adresses for each IP number thereby revealing the clickpath, entry points, exit points as well as aggregated hits. Based on this it becomes clear what links are missed, where broken links are located and importantly, reader persistence.
The program is implemented as a simple AWK script that parses 1000 hits in 20 seconds on a low end machine. The result is presented as a HTML table (600 KB sample from these web pages) which grows in width and height with the number of web pages in scope and can therefore be rather large. The new version of the script uses more CSS features, saving some space. The old version is still available. It is possible to save about 40 percent HTML code by dropping the </TR> tags.
Legend:
| Status: | Mockup only |
Documents need updates and feedback is useful. Wiki-style inputs is one method though some authors feel it can damage their reputation. The Ticket Tracker is a simpler solution that allows free form feedback on one side along with the original document on the other. This is simpler than using Bugzilla and has been in use on some standards documents in the past. Also this scheme allows for simple quality assurance. Summary of advantages:
| Status: | Working prototype |
This is a tar packaging of the latest versions of the HOWTO Generator and the Templates along with sample files. This should help in the cases where people hace been troubled by partial downloads. Latest download is available as tar file (ca. 220 KB) tar.gz file (ca. 70 KB) and zip archive (ca. 70 KB).
This is a small report on my experiences with Wikipedia to see how TLDP might benefit from a wiki approach, considering the software, the system and the processes. The conclusion was negative.
Return to homepage