[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: DocBook Technical Committee Meeting Agenda: 08 May 2019
With respect to open action item 5a, I have some notes about the reviewing of the extensions. My team has been slammed with a major release the last couple of weeks so I decided to tackle a fairly narrow part of this that I have some familiarity with â the area of enumerated types, which
I have used in multiple languages. I will likely tackle namespaces next time, since I donât really use languages that depend on macros to any great extent. I am sending these notes to avoid someone trying to type all this stuff in while we are talking about it. The conclusion I have come to is that the
enumsynopsis needs some work if it is to work for effective documentation of enumerated types. Here are my notes (which have some
inconsistencies since they were recorded as I ran into things and not redone to reflect insights that came up as the investigation continued). Notes on
enumsynopsis
1.
How to describe purpose of the enumerated type? Would a description or purpose element be appropriate?
2.
How to describe the significance of the enum identifier -- again, would an element specifically to represent this information be appropriate?
a.
some are obvious (color: red, blue, undefined)
b.
some need extra information (setup: fast, normal, secure)
3.
How to provide hints on how to render (table, similar to glossary, next level of section, etc.)
4.
How to indicate whether it is ordered or not.
5.
It's good that
enumvalue is optional since not all languages allow manipulation of the values directly like C-derived languages do.
6.
Is enumtype more reflective of programming than
enumname?
7.
Do we need to be able to represent implicit declaration of an enumeration (which could possibly make
enumname optional?):
8.
How to deal with "additional attributes":
9.
enumsynopsis has a lot of legal children and not much help on what is expected/required. In oXygen, an enumsynopsis becomes valid one an
enumname is added -- I think it probably should require a least one enumitem (which auto-populates with an
enumidentifier, which makes it much easier to use). I would suggest making an
enumname required as well as one or more
enumitems.
10.
We need to make sure that the descriptions bound into the schema are helpful since some of the elements could be a bit confusing.
11.
It would really help to have some samples of intended usage. Starting from scratch with the schema is not easy to come up with a reasonable sample. From: docbook-tc@lists.oasis-open.org [mailto:docbook-tc@lists.oasis-open.org]
On Behalf Of Scott Hudson DocBook Technical Committee Meeting Agenda: 08 May 2019
=============================================================
The DocBook Technical Committee will met on Wednesday, 08 May 2019
(11am PDT, 12noon MDT, 1pm CDT, 2pm EDT, and 8pm CET)
1. Roll call
2. Accept the minutes [1] of the previous meeting (10
April 2019)
3. Next meeting: 12 June 2019
4. Review of the agenda.
5. Review of open action items
a. Extension for synopsis elements (Issue #111)
ACTION: All to review info element proposals and provide any feedback to Bob. Bob submitted samples to list 11FEB2019.CONTINUED.
ACTION: All to review with someone familiar with various programming languages to see if this provides enough detail to map to various languages.
ACTION: Bob to send proposed structure to docbook-apps list to get additional input.
b. Larry to create an integrated proposal for legalsection, all to review before next meeting for approval. CONTINUED.
c. ALL: start work on action items earlier. CONTINUED
d. Scott to send a reminder mid-month. CONTINUED
6. Social media presence for DocBook
Purpose: To raise awareness of actions (votes, calls for information, etc.)
7. Review of Requests for Enhancement
To find a Github issue by number, enter the URL (on one line):
github.com/docbook/docbook/issues
117 Allow info in listitem associate some metadata with a listitem, but no place to put it.
Open Issues (Note: items that have been accepted are still open
on Github until included in a release,
but they are not listed here):
71 license tag
78 Schema website should be updated
88 DB 5.0: @name -> title change not published on docbook.org CLOSED
93 Diff between doc of resource element and Assembly schema
99 Add <endorsement> to <info>
Consider for Publishers.
100 DocBook 5.1 catalog.xml uses incorrect version
103 XML DTD of DocBook 5.1
111 DocBook
Library (tentative name) - Supercedes 107, 108, 109, 110
Links:
[1] https://www.oasis-open.org/apps/org/workgroup/docbook/email/archives/201904/msg00003.html
[2] http://github.com/docbook/docbook/issues
Thanks and best regards,
--Scott
Voting member:
Boeing Data Standards Technical Advisory Board
OASIS DocBook TC (Secretary), Publishers SC (Chair)
OASIS DITA TC, Tech Comm SC, LwDITA SC, Learning Content SC (Secretary)
OASIS DITA Adoption TC
OASIS Augmented Reality in Information Products (ARIP) TC
This document contains only administrative, uncontrolled data under U.S. International Traffic in Arms Regulations. |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]