[erlang-questions] how do I get emacs nXML to work with Erlang documentation? (with answer)
Wed Aug 31 14:04:08 CEST 2016
I have answers, but maybe someone can improve on them.
I want emacs to "behave" when editing xml from the OTP repo, e.g.
emacs tells me "Using scheme /usr/share/emacs/24.5/etc/schema/docbook.rnc
and isn't happy with the document. <header>, <p> and <list> are
naughty. (actually, it's the nXML mode, which is the default
mode for editing XML in recent emacs versions.).
Q1: What is this .rnc file emacs is looking at?
A1: .rnc and .dtd are both ways of defining what an XML document can
look like, with overlapping capabilities. You can automatically
convert one into the other, probably losing some information.
Wild speculation: someone felt embarassed that XML .dtds aren't
XML themselves, which might cause the plebs to think that the
empreror has no clothes. So someone invented a new format 'Relax'
which did more or less what DTDs do, in XML. But 'relax' was
embarassingly verbose. Someone else then invented yet another
format which was actually readable. The two inventors couldn't
agree on which syntax to keep, so a committee stepped in to be
decisive...and chose both.
Q2: Why isn't emacs looking at the .dtd?
A2: No idea. The .dtd can be converted to a .rnc automatically, so
nXML could do that on the fly. Maybe the nXML author wants to
hasten .dtd's death.
Q3: I just want to edit the file without seeing errors. How?
A3: M-x rnc-set-vacuous-schema
Now nXML will just check for well-formedness (e.g. your tags match up).
You can also do that from the XML menu.
Q4: I want to get nXML to check more than just well-formedness. How?
A4: Convert the .dtd into .rnc and tell nXML to use it. Here's one way:
sudo apt-get install trang // OS-specific; install 'trang'
cp /home/matthias/git/otp/lib/erl_docgen/priv/dtd/* .
cp /home/matthias/git/otp/lib/erl_docgen/priv/dtd_html_entities/*ent .
trang chapter.dtd chapter.rnc
you now have a .rnc file. You can tell emacs to use it with
C-c C-s C-f chapter.rnc
emacs will then dump a file in the same directory as the source
to remind emacs to use 'chapter.rnc' automatically next time.
For my workflow, it's easier to just use the vacuous schema.
Q5: Should Erlang's documentation build process migrate from .dtd
A5: I don't know. Wait-and-see is usually mostly painless.
More information about the erlang-questions