[MacPorts] #61176: Add instructions on updating the Guide's AsciiDoc sources (first, policy on AsciiDoc)

[MacPorts]

#61176: Add instructions on updating the Guide's AsciiDoc sources (first, policy on
AsciiDoc)
-------------------------+--------------------
 Reporter:  JDLH         |      Owner:  (none)
     Type:  enhancement  |     Status:  new
 Priority:  Normal       |  Milestone:
Component:  guide        |    Version:  2.6.3
 Keywords:               |       Port:
-------------------------+--------------------
 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".

-- 
Ticket URL: <https://trac.macports.org/ticket/61176>
MacPorts <https://www.macports.org/>
Ports system for macOS