Re: [Tools-discuss] [rfc-i] Proposed survey on I-D authoring tools

[Phillip Hallam-Baker <[e-mail]>]

I am not so sure what the value of asking what people do today is. The
question that really matters is what people would do if they knew what all
the options were.

I use Microsoft Word and Markdown to edit my specs. All the code is open
source but I seem to be the only person interested in this approach.

I edit the main body of the text in regular word format. I use regular
outlining etc. and it looks like word all the time I am editing. It does
not look like a plaintext rfc. That gives me spell checking and grammar.
Change control etc. also work.

The biggest deficiency of Word as a source format is that it is a pig to
generate from a tool. So I also use markdown similar to that used in
Carsten's tool but aligned with the markup used by GitHub because thats the
other tool we interact with.

So my word documents link to the generated markdown documents.


The tool will convert the Word/Markdown text into any of the input sources,
HTML, XML or plaintext output. Or all three.

The advantage of my approach is that it allows an editor who is using Word
to interact with contributors who insist on Markdown.

If you look at my output, I have produced 15 substantial drafts over the
past two years. The Mesh is similar in size and complexity to X.509v3 PKI
or SAML and I have designed and implemented it with very little outside
help. The reason I can do what would be a 30 person team at most companies
is that I am using a very powerful toolset that locks the documentation and
the code together.

Every example in my documents is generated from the reference code that is
derived from the same source as the schema. I am just implementing a tool
that locks the constant tables and cryptographic functions of the code and
documentation. It will be take me about four hours.