The directory of the Freedesktop.org Guidelines encompasses a compilation of conventional guidelines that have amassed over the years and delineate the operational mechanics of common desktop environments. These guidelines are crafted to enhance the compatibility among desktops. Common guidelines streamline the tasks for desktop-environment developers, particularly application developers (who typically seek to expand the Linux DEs their application can function on seamlessly, thereby broadening their applications’ reach).
Regrettably, constructing the HTML guidelines and upholding the catalogue of available guidelines has evolved into a somewhat arduous responsibility, as the process for constructing the site has grown outdated and neglected (with remnants reliant on Python 2). To simplify the task of maintaining this facet of Freedesktop, I endeavored to meticulously modernize the website. I harbor intentions of possibly restructuring the site in the future to enhance navigability, steering away from a mere alphabetical list of guidelines, and integrating it with the Wiki. However, in the interest of upholding backward compatibility and achieving tangible progress (rather than plunging into an insurmountable project), I chose to undertake the initial modernization to establish a functional website, deferring the additional modifications for later.
In summary: The majority of Freedesktop guidelines are now composed in DocBook XML. While some were basic HTML documents, others were in DocBook SGML, and a handful were in plaintext format. In an effort to facilitate maintenance, nearly every guideline is now scripted in DocBook. This also streamlines the review process, potentially enabling a transition to alternative formats like AsciiDoc down the line. Admittedly, alternatives to DocBook could have been explored, but that would have entailed a considerably larger endeavor with a plethora of broken links, which I aimed to circumvent by narrowing the scope of this project.
DocBook stands as a documentation markup language with a long-standing presence, affording it a suite of legacy tools. Thankfully, our allies at openSUSE devised DAPS (DocBook Authoring and Publishing Suite) as a contemporary means to render DocBook documents into HTML and other file formats. DAPS is now leveraged to generate all Freedesktop guidelines on our website. The website index and the revisions of the guidelines are also presently delineated in structured TOML files for enhanced readability and extensibility. Additionally, numerous guidelines that were not featured on the original website have been appended to the index and are now featured on the website.
Originally, I had intended to deploy the website in a temporary location to elicit feedback, particularly since some links had been altered and not all content may have redirects. However, owing to the operational dynamics of GitLab Pages (and my not possessing sufficient proficiency in GitLab CI…), the alterations went live prior to their MR being merged. Opting not to roll back the change, I opted to retain it (since the old website had ceased to build properly) and monitor for any disruptions. Thus far, no broken links or adverse effects have surfaced, but:
If you encounter any broken links to specifications.fd.o or any other anomalies, please report them so we can rectify the issues!
Thank you, and I trust you find perusing the guidelines in an enhanced format and a more cohesive presentation enjoyable! 😃
