Fri, 28 Feb 2020 07:54:49 +0000 Frank Beuth <secli...@boxdan.com> > On Fri, Feb 28, 2020 at 07:24:50AM +0100, Ingo Schwarze wrote: > >Hi Frank, > > > >Frank Beuth wrote on Fri, Feb 28, 2020 at 04:22:27AM +0000: > > > >> Is the web documentation (FAQ etc) included in the base system by > >> default anywhere, > > > >No it isn't. > > > >I offered some years ago to translate the FAQ from HTML to mdoc(7) > >and to include it in /usr/share/man/faq/ such that it would become > >available for both -current and -stable both online and offline > >without additional maintenance effort just like any other documentation > >and such that it would automatically be included in apropos(1) > >searches, but the proposal was rejected because the developers who > >actually maintain the content of the FAQ consider it easier to > >maintain in HTML than in mdoc(7) format. > > > >We don't want to lose the valued contributions of those developers > >who actually spend all the work maintaining the FAQ or make their > >work any harder than it is now. > > Thanks. Too bad the mdoc idea failed! >
Hi Frank, Maybe it just got deferred for the moment of more elegant (simplified) mandoc markup frontend editing. Editing HTML by hand is inconvenient + highly error prone at the same time as shown in many iterations of missing closing tag and other numerous errors hidden by the viewing pagers (error covering browsers). Editing HTML by hand should be reserved for fine tuning and maintenance of an export filter of a document specific authoring and editing convenient markup. Using mandoc for the purpose of system and accompanying documentation is "the best" current practice solution, it was designed for/in this specific domain. Lightweight markup formats are an enabler for document authoring and editing, as demonstrated by the largest online collaborative systems (encyclopaedias). At the same time, lightweight markup can optionally contain semantic (mandoc) markup and export cleanly to HTML, as mandoc can export to lightweight markup and HTML and other preformated (typeset) document output formats. An missing at the time system has never been an impediment to outstanding, and excelling work in the maintenance and preparation of the documentation as if it's here. Kind regards, Anton Lazarov MScEng EECSIT
