Add instructions on updating the Guide's AsciiDoc sources (first, policy on AsciiDoc)

[JDLH (Jim DeLaHunt)]

The MacPorts Guide (documentation) is generated from Docbook XML sources in macports-guide/guide/xml/*. In the Guide, 7.5. "Updating Documentation", 7.5.1. "Updating the Guide", there are instructions on editing these XML sources and submitting proposed changes. Good.

There is also a project underway to switch the Guide from Docbook sources to AsciiDoc sources (#56046). This has been underway for a couple of years. It works fairly well to use a tool to convert Docbook sources to AsciiDoc, stored in macports-guide/guide/adoc/*. But there are some imperfections. The resulting AsciiDoc sources need some hand-edits. It seems that right now the AsciiDoc sources are a parallel fork of the DocBook sources, not yet a replacement.

In the meantime, people are proposing changes to the Guide. They follow the instructions, which mention only the Docbook sources. There is no reason for them to know about the AsciiDoc fork of the Guide sources.

There is the usual problem with forks: insuring that changes to one fork be propagated to the other fork.

I propose that we add content to 7.5. "Updating Documentation" which tells about the AsciiDoc fork of the Guide source, and what documentation contributors should do about it.

In order to write that, it is necessary to decide what the policy is. I can imagine a few options:

1. Contributions must update the Docbook sources, and ignore the AsciiDoc sources. The consequence is that someone overwrites the AsciiDoc fork with a conversion from the Docbook sources from time to time, probably redoing manual fixups.

2. Contributions must update the Docbook sources, but updating the AsciiDoc sources is optional. The consequences are that someone will have to merge new AsciiDoc sources re-generated from Docbook with the existing AsciiDoc sources, probably redoing manual fixups. It might be that authors will author different AsciiDoc content than the conversion process generates.

3. Contributions must update the Docbook sources, then run the conversion process to keep the AsciiDoc sources in sync with the Docbook sources. This adds a barrier to entry for contributors. That would be ironic, because the goal of the conversion to AsciiDoc is to reduce the barrier to entry.

4. There are probably other possible policies.

What should the policy be?

Once I know the policy, I volunteer to write a draft of the AsciiDoc description in 7.5. "Updating Documentation".