[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Purpose of files in the scott-example-sandbox directory
Hi Scott,
I'm afraid I'm still confused about a couple things. (Maybe this is coming from my lack of sleep for the last two weeks?)
I'm not sure how these would become part of the test suite, since the TC does not maintain a test suite. That's been discussed at length in other threads. While this might be one way to get to one, the sample files should not be part of the TC SVN repository until there is some agreement that they are a useful approach, that they are comprehensive enough, and until there is some process for using them.
From a maintenance perspective, I really dislike the idea of maintaining two copies of every code sample. I've updated existing code samples and created new ones just in the last few weeks. This means samples you created based on 1.2 or even recent drafts of 1.3 are already out of sync with the specification. We're having a hard enough time dealing with the specification source itself that I wouldn't commit to manually maintaining two copies of every code sample.
If you want to continue to maintain this, I think it's best to do that someplace else, where it isn't confused with official TC-sponsored activities (in the same way that the RNG->DTD/XSD tools were recently moved out of SVN with their related specializations). Long term, if it does prove useful as a test suite, the TC could certainly designate it as a preferred approach or move the files into a more official status/location.
Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)
"Hudson, Scott" ---03/31/2015 11:55:20---IMO, they should still be a part of the test suite, then. We need to make sure that no changes are i
From: "Hudson, Scott" <scott.hudson@comtech-serv.com>
To: Robert D Anderson/Rochester/IBM@IBMUS
Cc: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>, "Kristen James Eberlein" <kris@eberleinconsulting.com>
Date: 03/31/2015 11:55
Subject: Re: [dita] Purpose of files in the scott-example-sandbox directory
How would you see them being used? The code samples for the specification are maintained within <codeblock> elements inside the specification source. I don't think we can or should change this.
From a practical perspective, Kris and I found several instances while updating the spec where descriptive text about a code sample no longer matched the sample itself. I think this is because over each release, samples had been fixed, expanded, or improved without looking at the surrounding text. That problem would increase significantly if the code samples were moved out and no longer tied to the context.
From a technical perspective, there is no standard way to pull markup from a valid DITA file and present only the relevant portion as a code sample. There are DITA-OT extensions to <coderef> that allow you to pull specific lines from a sample file, such as lines 5 to 10 -- but those extensions are non-standard. Using that method would likely break the specification as soon as somebody edited the sample file with a new editor, causing the text to flow differently.
Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)
"Hudson, Scott" ---03/31/2015 11:32:54---I still think these could be useful for validation and testing for 1.3, though they may need to be u
From: "Hudson, Scott" <scott.hudson@comtech-serv.com>
To: Robert D Anderson/Rochester/IBM@IBMUS
Cc: Kristen James Eberlein <kris@eberleinconsulting.com>, "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Date: 03/31/2015 11:32
Subject: Re: [dita] Purpose of files in the scott-example-sandbox directory
Hi Scott,
I'm still not sure what these files are for now? They are not part of the DITA 1.3 creation, review, or delivery, so I think SVN is probably not the right place for them. I'm nervous about them causing confusion when others start looking for official material, as we had with some of the extra files in the doctypes\ directory a few weeks back.
Also, as a related note, I think the bad examples from 1.2 have been corrected. They were never tested for XML (or DITA) validity during the 1.2 process, which is something we corrected for 1.3, resulting in tweaks to quite a few of the code examples.
Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)
"Hudson, Scott" ---03/31/2015 10:44:17---Kris, et al, These files take all of the examples from the DITA 1.2 Specification (http://docs.oasis
From: "Hudson, Scott" <scott.hudson@comtech-serv.com>
To: Kristen James Eberlein <kris@eberleinconsulting.com>, "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Date: 03/31/2015 10:44
Subject: Re: [dita] Purpose of files in the scott-example-sandbox directory
Sent by: <dita@lists.oasis-open.org>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]