OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita-adoption message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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/resourceNaming.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/resourceNamingCommentaryV08.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
>
>


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]