[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: SSTC document guidelines
"Eve L. Maler" wrote: > > Here are just a few comments on the SSTC Document Guidelines Some comments on Eve's comments. Others have thoughts to contribute? thanks, JeffH > At 12:52 AM 1/31/01 -0800, Jeff Hodges wrote: > >Bob & I collaborated on modifying the document guidelines doc he posted last > >week. Present OASIS-specific version is below. Comments encouraged. > > [..snip..] > > > >3.2 Naming > > > >Committee documents MUST be named using the format: > > > > "draft-sstc-" + [ subcommittee mailing list acronym + "-" ] > > + short title + "-" + two-digit version + "." + doc format > > > > e.g. "draft-sstc-core-assertions-05.html". > > For HTML documents, any chance we can standardize on either .htm or .html, > but not both? It would be annoying for people to guess wrong on the > extension, when the rest of the filename is so well structured. I'm professionally agnostic, I agree we should just pick one and solicit input from others (tho I personally favor ".html" since ".htm" is pretty much just a holdover Windows-ism (if I understand the lineage correctly)). I just asked Karri Myles, our webmaster, what he thinks -- he's going to be doing a fair amount of the work managing the SSTC pages -- and he favors ".html". > >Individual submissions MUST be named using the format: > > > > "draft-" + main author's last name + "-" + short title > > + "-" + two-digit version + "." + doc format > > > > e.g. "draft-morgan-coolidea-00.txt". > > > > > >5.3 Formats > > > >PDF format is preferred distribution document format. Document > >source formats are XML encoded according to the XXX DTD for text, > >and Powerpoint source for illustrations (one illustration per > >powerpoint slide, one powerpoint file containing multiple slides > >per corresponding XML textual source file). > > Was PDF the agreement of the folks who collaborated on these guidelines? I > thought we were going for HTML. .html is the desired-by-BobB, "interim", work-product editable format, as discussed in these messages.. http://lists.oasis-open.org/archives/security-services/200101/msg00094.html http://lists.oasis-open.org/archives/security-services/200101/msg00095.html ..and the non-editable, "output format" (or "distribution document" format) is presently agreed upon to be .pdf (see the above two msgs). > Also, I'd like to standardize on JPEG, at > least as the "non-revisable" version of a graphic. Just about anything can > output .jpg. Yes. Again, referring to the above two msgs, .ppt is the presently-agreed-upon "source" format for illustrations, while .jpg is the "non-revisable" aka "output format" aka "distribution format" for illustrations. > > >5.4 Content elements > > > >A document must include, at the beginning, the author's names, the > >date of submission, the document name including version number, the > >name of the working group, and an email address to which comments can > >be directed. A document must include, at the end, author contact > >information for all authors, including at least an email address for > >each. > > I would like to see all the "metadata," including author contact > information, at the top so that it's all in one place. Of course, if we > use sufficiently structured XML (e.g. XMLspec or a derivative), we can > generate the output to put this stuff in any order we like. > > FWIW, here's what W3C documents typically have in the header; these > examples are taken from http://www.w3.org/TR/REC-xml and they're all > formally covered in the XMLspec DTD. I think it would be nice to have at > least all those with *: > > *Title (e.g., "Extensible Markup Language (XML) 1.0 (Second Edition)") > Type of document (e.g., "W3C Recommendation") > *Date of publication (e.g., "6 October 2000") > *Official URI of publication (e.g., > "http://www.w3.org/TR/2000/REC-xml-20001006") > Generalized URI of latest version > URI for most recent previous version > *Authors/editors and contact information > Copyright statement > *Abstract > *Status of This Document > > This week I will attempt to make a derivative of XMLspec (or simply its > stylesheets) that might meet our needs. Super, that'd be great. Sure, we're open to revising where in the doc metadata oughta be placed. I think we should include "type of document" in your * list. And, to the extent that it's pretty easy to do (see the end of draft-sstc-doc-guidelines-02.txt; we can provide a .txt and/or .html file template), subcomm and TC drafts SHOULD have the IPR and Copyright notices placed in them. [..snip..]
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC