Next in thread →
Next in month →
Re: [chairs] RE: EXT :RE: EXT :Re: [chairs] Re: Document numbering
Kristen, I agree and this is moving off topic. Â
Thanks,
Bret
PGP Fingerprint:Â63B4 FC53 680A 6B7D 1447 ÂF2C0 74F8 ACAE 7415 0050
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."
On Tue, Oct 6, 2020 at 8:43 AM Kristen James Eberlein <> wrote:
Folks, line numbering is SO not applicable if the authoritative
format is HTML or XML.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
On 10/6/2020 10:37 AM, Lemire, Dave
(HII-TSD) wrote:
This
might be useful for the TCADMIN team; I think itâs simpler
than the process theyâve been using for MD to PDF and IIRC
the current process made line numbering PDFs difficult.
Â
I
canât envision why Iâd used Open/Libre Office to edit MD
files when VSCode integrates so nicely w/git and GitHub.
Â
However,
I think weâre drifting off topic.Â
Â
Dave
Â
David
Lemire
HII
Mission Driven Innovated Solutions (HII-MDIS)
Technical
Solutions Division
302
Sentinel Drive | Annapolis Junction, MD 20701
Work
(301)Â575-5190 |
MobileÂ(443)Â535-1182
Â
From:
Considine, Toby [mailto:]
Sent: Tuesday, October 6, 2020 10:30 AM
To: Lemire, Dave (HII-TSD)
<>; Bret Jordan
<>
Cc: Ericson, George
<>; Stefan Hagen
<>; Chet Ensign
<>; OASIS TAB
<>; Martin Chapman
<>;
; Guy Martin
<>
Subject: EXT :RE: EXT :Re: [chairs] Re: Document
numbering
Â
CAUTION: This email originated from
outside
your organization. Exercise caution when opening
attachments or clicking links, especially from unknown
senders.
Â
Writage
is a currently free MS Word add-in that reads and writes
MD, lets you pull in any MD, add line numbers, save as
PDF. Line numbers will change in Word and other formats
based upon the printer in use, so the PDF step is useful
to make them immutable. I do not know any way to add line
numbers in MD printed output (which is all you need to get
into PDF) at this time.
Â
The
same sort of round tripping into a published artifact
works quite well for Google docs.
Â
The
Fintech guys, who use MD in *their* github work
recommend editing MD files in OpenOffice or LibreOffice.
Both OpenOffice and LibreOffice support line numbering as
well, and each can of course print to the immutable PDFs.
Â
Â
A
quick search suggests that adding attr.output =
".numberLines" to MD files makes them number directly when
printed, but I have no experience with that.
Â
tc
Â
Â
From:
Lemire, Dave (HII-TSD) <>
Sent: Tuesday, October 6, 2020 10:04 AM
To: Considine, Toby <>;
Bret Jordan <>
Cc: Ericson, George <>;
Stefan Hagen <>;
Chet Ensign <>;
OASIS TAB <>;
Martin Chapman <>;
;
Guy Martin <>
Subject: RE: EXT :Re: [chairs] Re: Document
numbering
Â
Iâll
note that line numbering is easy if youâre working in a
traditional word processor. Itâs much harder when youâre
creating in markdown and publishing in markdown and HTML.
I guess you can refer to line numbers in the markdown text
source.
Â
Dave
Â
David
Lemire
HII
Mission Driven Innovated Solutions (HII-MDIS)
Technical
Solutions Division
302
Sentinel Drive | Annapolis Junction, MD 20701
Work
(301)Â575-5190 |
MobileÂ(443)Â535-1182
Â
From:
Considine, Toby [mailto:]
Sent: Monday, October 5, 2020 2:31 PM
To: Bret Jordan <>
Cc: Ericson, George <>;
Stefan Hagen <>;
Chet Ensign <>;
OASIS TAB <>;
Martin Chapman <>;
;
Guy Martin <>
Subject: EXT :Re: [chairs] Re: Document
numbering
Â
CAUTION: This email originated
from
outside your organization. Exercise
caution when opening attachments or clicking
links, especially from unknown senders.
Â
Maybe
that goes back to why I believe that the review copies
of each document must include line numbers.Â
Â
If
you comment is that in WD047 that there is some
confusion in lines 137-144, I can as editor easily
find the text, easily say "Oh, we deleted two
paragraphs, so that is now lines 114-121, and I can
see the confusion"
Â
As
an editor I always valued all those comments, because
it meant someone was at least reading it.
Â
tc
Â
Â
Â
Â
From: Bret
Jordan
Sent: Monday, October 5, 2020 2:00 PM
To: Considine, Toby
Cc: Ericson, George; Stefan Hagen; Chet
Ensign; OASIS TAB; Martin Chapman;
;
Guy Martin
Subject: Re: [chairs] Re: Document numbering
Â
Yeah, the conceptual high level
theory is great. The wheels fall off the bus when
you get into the specifics and actually have to
relate which version is which. This is where
things go bad really quick.Â
Â
Thanks,
Bret
PGP
Fingerprint:Â63B4 FC53
680A 6B7D 1447 ÂF2C0 74F8
ACAE 7415 0050
"Without
cryptography vihv vivc ce
xhrnrw, however, the only
thing that can not be
unscrambled is an egg."
Â
Â
On Mon, Oct 5, 2020 at 11:37
AM Considine, Toby <>
wrote:
I've
been on stages talking to hundreds of
people about the progress of current OASIS
work, and the difference between WD and
CSDs, and then entertained questions from
the audience.
Â
There
never seemed to be any confusion. The most
frequent reaction was to be impressed by
the clarity and openness of the documents
and numbers, particularly by those who had
worked in some of the other standards
groups.
Â
Â
From: Bret
Jordan
Sent: Monday, October 5, 2020
1:03 PM
To: Ericson, George; Stefan Hagen
Cc: Chet Ensign; OASIS TAB;
Martin Chapman;
; Guy
Martin
Subject: Re: [chairs] Re:
Document numbering
Â
I would be all for
a consistent and easy to understand
system. I know Stefan had a proposal
for semantic versioning at one point.Â
The point is we really need to fix and
improveÂthis. The fact that an
outsider to OASIS can not have a clear
understanding of the status of a
document is just nuts and when that
outsider tries to talk to a TC member
and the TC member is used to working
on a Working Draft number and the
outsiderÂis talking about Version 1.0
or version 2.1 and the TC member is,
but which CS or CSD or WD number are
you actually talking about.Â
Â
Thanks,
Bret
PGP
Fingerprint:Â63B4 FC53 680A 6B7D 1447 ÂF2C0 74F8 ACAE 7415 0050
"Without
cryptography
vihv vivc ce
xhrnrw,
however, the
only thing
that can not
be unscrambled
is an egg."
Â
Â
On Mon, Oct 5,
2020 at 10:51 AM Ericson, George
<>
wrote:
In
other groups we have done
something like this:
Â
There is a distinction between
a release number and a
document version.
A release number is m.n.p
where:
m is a major release.
n is a minor release. No
backwards incompatible
changes are allowed within
the same major release, with
exception of corrections.
p is a correction to a minor
release. It may introduce a
backwards incompatible
correction if the correction
is necessary and in line
with the original intent.Â
It may not introduce new
functionality.
The document version number is
incremented automatically by
Higher Logic on upload.
Documents are self-defining:
ÂEach document carries its
revision number and its
status, like 'draft', 'for
approval', 'approved'.
The document revision number
of each document version is
the intended approved revision
number.
Â
This
captures the difference
Alternative
proposal
Original
Proposal
Version
Revision
Status
1
1.0.0
Draft
WD
01
2
1.0.0
Draft
WD
02
3
1.0.0
Draft
WD
03
Â
Â
Â
CSD
01
4
1.0.0
Draft
WD
04
5
1.0.0
Draft
WD
05
Â
Â
Â
CSD
02
6
1.0.0
For
approval
CSPRD
01
7
1.0.0
Draft
WD
06
Â
Â
Â
CSD
03
8
1.0.0
Draft
WD
07
Â
Â
Â
CSD
04
9
1.0.0
For
approval
CSPRD
02
10
1.0.0
Approved
CS
01
11
1.1.0
Draft
WD
08
Â
Â
Â
CSD
05
12
1.1.0
For
approval
CSPRD
03
13
1.1.0
Approved
CS
02
Â
George
Â
Â
From: Bret Jordan <>
Sent: Monday, October 5,
2020 12:00 PM
To: Chet Ensign; OASIS
TAB; Martin Chapman;
Subject: [chairs] Re:
Document numbering
Â
Oh and do not forget that the
documents also have a Version
number that somehow has to be
correlated to a CSD / CS
version as well. Honestly,
the way we do document
versioning is just a mess and
inconsistent TC to TC. So you
could have:
Â
Version 3.1.4 =ÂCS 02 =
CSPRD = 03 = CSD 05 = WD 08
Â
Thanks,
Bret
PGP
Fingerprint:Â63B4 FC53 680A 6B7D 1447 ÂF2C0 74F8 ACAE 7415 0050
"Without
cryptography
vihv vivc ce
xhrnrw,
however, the
only thing
that can not
be unscrambled
is an egg."
Â
Â
On Mon, Oct 5, 2020 at 9:51
AM Bret Jordan <>
wrote:
Chet, et al.,Â
Â
Please forward to the
process committee.Â
Â
As a board member I
worked on trying to
remove the working draft
concept and have us just
use CSDs. However, given
that CSDs require some
sort of formal
approvalÂto release, aka
a ballot, then we still
have a problem. It comes
from document numbering
and being able to
release documents on a
routine basis.Â
Â
Old System: (we
understand the confusion
and problems really well
with this system)
WD 01
WD 02
WD 03
CSD 01
WD 04
WD 05
CSD 02
CSPRD 01
WD 06
CSD 03
WD 07
CSD 04
CSPRD 02
CS 01
WD 08
CSD 05
CSPRD 03
CS 02
Â
So a TC only really
reviews and works on
working drafts. Yes,
some only review CSDs,
but that is not the
majority of active
people. So in this old
model we have CS 02 =
CSPRD = 03 = CSD 05 = WD
08. An utter mess.
Â
With the new proposed
model, there is no real
semantic way of
versioning the documents
between approved
releases of CSDs. So it
makes it really
difficult to keep track
of what version you are
working on. So much
added complexity. About
the best you can do is
something like:
Â
CSD 00.1
CSD 00.2
CSD 00.3
CSD 01.0 (approved
release)
CSD 01.1 (should this
minor version restart or
should it continue like
the WDs did)
CSD 01.2
CSD 02.0 (approved
release)
CSD 02.1
CSD 03.0
(approved release)
CSPRD of CSD 03.0
CSD 03.1
CSD 04.0
(approved release)
CSPRD of CSD 04.0
CS 01
CSD 04.01
CSD 05.0
CSPRD of CSD 05.0
CS 02
Â
SO CS 02 = CSD
05.0. This still
seems a bit
confusing. Maybe
we do something
like the
following. This
would keep a
consistent
semantic number
scheme regardless
of the delivery
"stage".
Â
CSD 0.0.1
CSD 0.0.2
CSD 0.0.3
CSD 0.1.0
(approved
release)
CSD 0.1.1
(should this
minor version
restart or
should it
continue like
the WDs did)
CSD 0.1.2
CSD 0.2.0
(approved
release)
CSPRD of CSD
0.2.0
CSD 0.2.1
CSD 0.3.0
(approved
release)
CSPRD of
CSD 0.3.0
CSD 0.3.1
CSD 0.4.0
(approved
release)
CSPRD of
CSD 0.4.0
CS 1.0.0
CSD 1.0.1
CSD 1.1.0
(approved
release)
CSPRD of
CSD 1.1.0
CS 2.0.0
Â
If we could get
out of the notion
of having CSDs be
formally approved.
Maybe the TC can
have a standing
rule that they can
be released weekly
or twice a month
or when the Chairs
and Editors find
them to be in a
good state. This
would give us the
following.Â
Â
CSD 0.1
CSD 0.2
CSD 0.3
CSD 0.4
CSPRD of CSD
0.4
CSD 0.5
CSPRD of
CSD 0.5.0
CSD 0.6
CSPRD of
CSD 0.6
CS 1.0
CSD 1.1
CSPRD of
CSD 1.1
CS 2.0
Â
Obviously this is
SO much easier and
cleaner.Â
Â
Thanks,
Bret
PGP
Fingerprint:Â63B4 FC53 680A 6B7D 1447 ÂF2C0 74F8 ACAE 7415 0050
"Without
cryptography
vihv vivc ce
xhrnrw,
however, the
only thing
that can not
be unscrambled
is an egg."
Attachment:
smime.p7s
Description: S/MIME Cryptographic Signature
Next in thread →
Next in month →