[erlang-questions] how do I get emacs nXML to work with Erlang documentation? (with answer)

[Matthias Lang]

Hi,

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 lib/kernel/doc/src/notes.xml

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
    to .rnc?

A5: I don't know. Wait-and-see is usually mostly painless.

Matt