documentation: remove docbook in favour of asciidoc #290
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ThomasAdam
force-pushed
the
ta/man-to-asciidoc
branch
2 times, most recently
from
7dcecd3
to
d627ad1
Compare
ThomasAdam
changed the title
ThomasAdam
force-pushed
the
ta/man-to-asciidoc
branch
from
d627ad1
to
896240d
Compare
Many years ago, documentation in fvwm went from raw manpages to docbook format as a canonical source. The idea was that this horrific XML source could generate both manpages and HTML files. This worked fine, however it meant that writing documentation became an horrendous chore -- the XML markup was verbose, unsightly and got in the way of actually documenting anything. Although markup languages have an overhead, asciidoc seems like a good replacement for bringing back the documentation to as close to plain text as possible -- and can still generate the single-source files to other output formats beyond just man pages. This commit does a few things: * Converts roff output to asciidoc (originally via Pandoc) * Removes docbook support * Hooks in asciidoc * Updates CI/CD The asciidoc generator of choice is `asciidoctor`. HTML generation of documentation has been removed. Hence, the option of `--enable-htmldoc` via `./configure` no longer exists. Although this commit should be several small ones, getting this to build incrementally is difficult.
ThomasAdam
force-pushed
the
ta/man-to-asciidoc
branch
from
896240d
to
1b6ab10
Compare
ThomasAdam
added
the
type:breaking
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Many years ago, documentation in fvwm went from raw manpages to docbook format as a canonical source. The idea was that this horrific XML source could generate both manpages and HTML files.
This worked fine, however it meant that writing documentation became an horrendous chore -- the XML markup was verbose, unsightly and got in the way of actually documenting anything.
Although markup languages have an overhead, asciidoc seems like a good replacement for bringing back the documentation to as close to plain text as possible -- and can still generate the single-source files to other output formats beyond just man pages.
This commit does a few things:
The asciidoc generator of choice is
asciidoctor.HTML generation of documentation has been removed. Hence, the option of
--enable-htmldocvia./configureno longer exists.Although this commit should be several small ones, getting this to build incrementally is difficult.