Notes

LUFDOC is designed so that the docs are integrated with documentation generator tools such as FPDOC. FPDOC creates the skeleton, while LUFDOC allows trusted users and developers to edit the descriptions, examples, notes, and comments.

One can create new pages without being tied to a specific fpdoc html page. For example, this page you are reading right now is not tied to a specific Pascal unit.

LUFDOC could work with other documentation generator tools. However, FPDOC was chosen as the first supported one for now, since it creates nice skeletons of HTML files that are easily tapped onto.

The API guide link at the top of the page contains the fpdocs. If it is currently empty, then that's just because we haven't uploaded any fpdoc files yet. When you land on a page that is tied to a FPDOC html page, the declaration is shown just like on the fpc website docs.. but underneath the declarations we can add notes dynamically with our web browser, instead of the notes being fixed XML files that are compiled at design time.

Instead of XML we use square bracket HTML syntax (more powerful than BBcode) so it is easy to type and read the files.

Downloading Offline Docs

In the future, LUFDOC will be able to export a snapshot of the entire docs at once with a single click. You'd be able to download a zip or tar file containing all html docs as a static snapshot.

What Export Formats?

Right now.. it can be exported as static HTML page, or a combination of a static HTML header and footer along with LUFDOC syntax for the body content (the notes and examples). It will be able to export PDF/TXT/XML and other formats in the future.

Today, XML/RSS dumps are hyped, but other times having tab delimited dumps or HTML dumps is nice too. In other words, there is not one single format that is superior. Dumps solve that problem.

Ways to View The Docs

Currently through web browser.

In the future, we can offer PDF dumps, text file dumps. It all depends on what people really demand. Most of us are just happy to have any sort of documentation at all.. especially documents that are updated frequently due to having a system like LUFDOC that allows them to be updated without difficulty.

Offline HTML viewer programs could be created to read the dumps on a local disk, too. IDE html viewers could also be created. Or people can use TCP/IP software to connect to a server without using a browser (some GUI based help tool). However, the easiest way to veiw the docs is to just hook up your IDE/Editor tools menu to point to these docs. Using the lufind tool you can find pages based on the current token or current selection in your editor.

LUFDOC Syntax For Editing The Docs

It is like BBcode but more powerful. It uses square brackets and is prettier than html or xml. We prefer writing the docs in a nice format, and then being able to dump them to other formats as an option. We chose this route instead of writing everything in XML. The reasoning: you can always dump as XML, you don't necessarily need write XML! XML is more of a language that computers can parse and read. Human eyes, fingers, and arms have trouble with XML.

Syntax improvements to lufdoc: we will be getting rid of the paragraph tag requirement. Carriage returns will be converted into <p>'s automatically for you. LUFDOC will also have other syntax shortcuts added with time that are fully backward compatible with the old longer form square bracket html-like syntax that LUFDOC was originally built on.

How LUFDOC and FPDOC work Together?

FPDOC has an option to static html files (using --output command line option). After building the HTML files a LUFDOC post processor tool goes over the HTML files and converts them into slightly different HTML without any HEAD/BODY tags. They contain snippets of HTML rather than full HTML pages. Also, HREF links are changed to suit a cgi program instead of static HTML. The post processor tool does all this parsing automatically and creates a new copy of LUFDOC skeletons which are just modified FPDOC skeletons.

Then a CGI program can be used to display these snippets of docs.. and underneath the snippets are notes and examples contributed by you and I inside our web browser (or inside other software that connects to the lufdoc files). The notes and examples are contributed underneath the docs and stored as separate files. This way one can detach the FPDOC skeleton files from the notes and example text.

One can take a snapshot of the docs and convert the LUFDOC pages as static HTML that doesn't rely on any CGI program. That way, those conscious of server bandwidth can make caches and snapshots of documentation at intervals.. instead of requiring a CGI program to be loaded every time one wants to read the docs online.

The CGI program is just one way of editing the docs. One could also build a TCP/IP native application to view and edit them. Since most people have an internet browser installed and most people are lazy, this CGI program is really handy, even if editing documentation in a browser is not as ideal. For those that want to edit the docs in their IDE, a IDE tool or plugin could be created for that purpose. LUFDOC was designed from day one to be decoupled from any GUI. The possibilities are limitless therefore, when considering view/edit tools for LUFDOC files.

LUFDOC does not currently use a database to store the documentation.. but it may have this available as an option in the future. It currently uses files, locking, and a conflict notification system if two developers happen to edit at the same time. In the future a comment system will be added so users passing by can add comments under the docs.

Where to download LUFDOC?

Download link is coming soon.

Does LUFDOC use XML Descripton Files

No, LUFDOC just uses lufdoc's own 'description' files. These files are editable in the web browser. The HTML skeletons that FPDOC generates are used (but modified first, with HTML and BODY trimmed) . The descriptions and documentation are made here in your browser or through LUFDOC software that connects to the documentation. Underneath the HTML skeletons we add notes using LUFDOC syntax, and these notes are stored in a separate file.

The LUFDOC description files use a syntax like BBCode, but more powerful.. about as powerful as HTML, with more syntax short cuts being added with time (so that it gets much easier to use over time, while remaining backwards compatible).

Why not XML?

Short answer: you can still dump documentation as XML! You don't have to write it in XML in the first place, that's all. Of course, people don't want to take the time to write a dump tool, or they feel that by using XML they are being standards compliant. Well, modern Pascal is not Standard Pascal for a reason.. it is to cater to the users. To make it easier for users to use Pascal we have extended Pascal. So to make it easier for users to use LUFDOC we have given them cleaner syntax to use when editing the docs. The LUFDOC BBCode-style is being improved over time with quicker syntax options. But the old longer syntax is still there for backwards compatablity.

I don't mind the FPDOC XML files, since they work, but I'm also not a huge fan of XML either. You've either got people complaining that XML is too hard to use and too hard to read, or you've got people complaining that your files aren't standard compliant. The users are more important.. so we should cater to the users and not always to overly general standards. There is no holy grail. Actually, there is. Simply build an XML dump tool and you have the best of both worlds: write docs easily, and dump them as XML if you really need to. Or dump them as HTML or TXT or PDF. Or convert them to XML and then to PDF.

Seems like a lot of options? Well, most people could care less about all these XML/TXT/PDF docs... they just want to read and edit the docs easily. Lots of people know BBCode style syntax since lots of people visit forums with BBCode. a few people know (some limited) XML too, but BBCode is quicker and cleaner.

See also XML or Not?