RE: [dita-adoption] KAVI categories

[Robin Cover <robin@oasis-open.org>]

Gershon, thanks for the heads-up.  Your revised proposal
represents a definite improvement, from the POV considered
earlier.

Best wishes,

  - Robin

Robin Cover
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email: robin@oasis-open.org
Staff bio: http://www.oasis-open.org/who/staff.php#cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783


On Mon, 9 Feb 2009, Gershon Joseph (gerjosep) wrote:

> Hi Robin,
>
> Thanks for this input. I hereby modify my file naming recommendation as
> follows:
>
> An additional item that we need to decide on is naming conventions for
> documents uploaded to the KAVI system. For the new feature articles we
> are developing for DITA 1.2, I suggest "dita-120-feature-<name of
> feature>.<extension>. I also suggest we use camelCase for the feature
> description part of the filename. The 3-digit number of the DITA release
> allows us to cater for minor releases of the spec, should the DITA TC
> ever release them. So release 1.2.1 would get the prefix "dita-121", and
> so forth.
>
> I expect each feature article would be uploaded as a zip file,
> containing complete source as well as generated PDF and HTML. So then
> our current feature articles would be uploaded with the following
> filenames:
>
> * dita-120-feature-linkManagement.zip
> * dita-120-feature-keyRef.zip
> * dita-120-feature-taskModels.zip
>
> All TC members: Please let me know what you think of this file new
> naming proposal. The idea is to identify the articles specific to a DITA
> release.
>
> Thanks,
> Gershon
>
>
>
> -----Original Message-----
> From: Robin Cover [mailto:robin@oasis-open.org]
> Sent: Monday, January 12, 2009 6:51 PM
> To: Gershon Joseph (gerjosep)
> Cc: DITA Adoption TC; Robin Cover
> Subject: RE: [dita-adoption] KAVI categories
>
> Hi Gershon,
>
> I noted the following suggested pattern, which uses the UNDERSCORE
> character:
>
>> *     dita_1.2_feature_link_management.zip
>> *     dita_1.2_feature_keyref.zip
>> *     dita_1.2_feature_task_models.zip
>
> I would encourage you to consider the language of the OASIS Naming
> Guidelines on the matter of using UNDERSCORE in filenames (hence: in
> URIs).
>
> http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNamin
> g.html#nameCharacters
>
> The Guidelines note that TCs are allowed to use UNDERSCORE in cases
> where use of hyphen is impractical or undesirable.  Is there some
> technical reason not to use HYPHEN instead? (Or alternately, CamelCase,
> per below)
>
> The Guidelines were written to reflect a strong consensus by OASIS
> members who were asked about the pros and cons of UNDERSCORE in
> filenames.
> The UNDERSCORE character introduces several well-known liabilities.
>
> The rationale for this guidance is summarized below and in the resources
> referenced.
>
> ----------------------------------------------------------------------
>
> [...]
>
> * In most contexts, allowable name characters include [0-9A-Za-z]
>   plus "."(period) and "-" (hyphen)
> * Underscore is ("_") allowed in designated contexts where use of
>   hyphen is impractical or undesirable
>
> NOTE: TC members involved in naming are encouraged to consider the
> context in which URIs are likely to be used; in some print media, the
> UNDERSCORE character is indistinguishable from other "blank"
> characters, and in the context of common Web practice, may be ambiguous.
> See the following note.
>
> http://xml.coverpages.org/ADMIN/blanks/
> http://xml.coverpages.org/ADMIN/blanks/examples.pdf
> http://xml.coverpages.org/ADMIN/blanks/examples.txt
>
> For this reason:
> http://docs.oasis-open.org/specGuidelines/namingGuidelines/resourceNamin
> gCommentaryV08.html#camelCase
>
> The most common strategies for creating names from a sequence of words
> or morphemes (closed compounds) include use of an explicit delimiter
> character (e.g., HYPHEN) or marking juncture by camel case. Both
> strategies are intended to enhance readability for the human user. In
> some programming languages (by no means all), the underscore character
> may be used to join word components.
> This usage is probably benign. In the context of the World Wide Web,
> where use of the [not-hex-escaped] SPACE character within filenames
> (thus URIs) is exceedingly popular, the use of the underscore character
> to mark juncture may be deleterious, since typically it will be rendered
> as an ambiguous BLANK character in certain print media.
>
> Therefore:
>
> * HYPHEN is preferable to UNDERSCORE in many cases
> * CamelCase is also a very common design pattern for
>   component construction (-->> filenames and URIs)
>
> On CamelCase as one preferred naming method, see:
>
> http://xml.coverpages.org/camelCase.html#NDRs
>
> -----------------------------------------------------------------------
>
> Thanks for your consideration in this matter.
>
> - Robin Cover
>
> Robin Cover
> OASIS, Director of Information Services
> Editor, Cover Pages and XML Daily Newslink
> Email: robin@oasis-open.org
> Staff bio: http://www.oasis-open.org/who/staff.php#cover
> Cover Pages: http://xml.coverpages.org/
> Newsletter: http://xml.coverpages.org/newsletterArchive.html
> Tel: +1 972-296-1783
>
>
> On Mon, 12 Jan 2009, Gershon Joseph (gerjosep) wrote:
>
>> Hi all,
>>
>> Aside from JoAnn's OK, I have not received any other feedback on the
>> list of categories. If I get no further input by COB Tuesday 13 Jan, I
>
>> will pass this request on to Mary.
>>
>> Gershon
>>
>> ________________________________
>>
>> From: JoAnn Hackos [mailto:joann.hackos@comtech-serv.com]
>> Sent: Tuesday, January 06, 2009 6:52 PM
>> To: Gershon Joseph (gerjosep); DITA Adoption TC
>> Subject: RE: [dita-adoption] KAVI categories
>>
>>
>>
>> Looks good to me.
>>
>> JoAnn
>>
>>
>>
>> JoAnn Hackos PhD
>>
>> President
>>
>> Comtech Services, Inc.
>>
>> joann.hackos@comtech-serv.com
>>
>> Skype joannhackos
>>
>>
>>
>> ________________________________
>>
>> From: Gershon Joseph (gerjosep) [mailto:gerjosep@cisco.com]
>> Sent: Tuesday, January 06, 2009 4:40 AM
>> To: DITA Adoption TC
>> Subject: RE: [dita-adoption] KAVI categories
>>
>>
>>
>> Hi all,
>>
>>
>>
>> Please review this list of KAVI categories and let me know if you have
>
>> any changes or comments. Please send me your feedback by COB Friday 9
>> January 2009.
>>
>>
>>
>> *	Calendar Documents (used for calendar events, such as TC
>> meetings)
>> *	Meeting Notes (used for meeting minutes)
>> *	Related Standards (standards related to the work of the DITA
>> Adoption TC
>> *	Best Practices (various best practice documents, including
>> feature articles)
>> *	White Papers (SWOT analysis, marketing documents, conference
>> presentations)
>> *	Use Cases (customer and organization use cases)
>> *	Proposals (proposals for new DITA features develop by this TC to
>> be taken to the DITA TC)
>>
>> An additional item that we need to decide on is naming conventions for
>
>> documents uploaded to the KAVI system. For the new feature articles we
>
>> are developing for DITA 1.2, I suggest "dita_1.2_feature_<name of
>> feature>.<extension>.
>>
>> I expect each feature article would be uploaded as a zip file,
>> containing complete source as well as generated PDF and HTML. So then
>> our current feature articles would be uploaded with the following
>> filenames:
>>
>> *	dita_1.2_feature_link_management.zip
>> *	dita_1.2_feature_keyref.zip
>> *	dita_1.2_feature_task_models.zip
>>
>> Please let me know what you think of this file naming proposal. The
>> idea is to identify the articles specific to a DITA release.
>>
>>
>>
>>
>>
>> Thanks,
>>
>> Gershon
>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>
>