[LSC] Proposed changes to the LDraw part header to support the CA
-Version 5
VIVAN Guy
guy_vivan at infonie.fr
Fri Sep 1 15:35:23 EDT 2006
It's OK to me ;o)
----- Original Message -----
From: Travis Cobbs
To: LDraw Standards Committee
Sent: Friday, September 01, 2006 6:53 PM
Subject: [LSC] Proposed changes to the LDraw part header to support the CA -Version 5
OK, I'm sending out another version. We need to get this approved ASAP. People are complaining about the lack of another part update, and it seems that this is currently the gating item.
Based on discussion (mainly Steve's input) I removed the END-OF-HEADER meta-statement. I agree with Steve on this, and though he's not on the LSC now, if the part tracker has no need to track the end of the header, I don't see a need for the statement. We can debate this if people feel strongly about it, but since nobody responded to Steve's statement that it's not needed, I'm removing it. Frankly, if you disagreed, you probably should have responded to Steve's email.
I've removed the 0 !OTHER... line. This wasn't discussed by anyone, but we shouldn't have any meta-commands in the part header that aren't listed. It's perfectly ok for any meta commands to appear after the part header, but the header should only include approved meta-commands. I added a statement to this effect. There wasn't any discussion by anyone on this point. If you disagree with me here, now's the time to say so.
I've also indicated which statements are optional. I included the BFC command in this list, because right now it's optional. If we want to make this mandatory (with NOCERTIFY for parts that aren't BFC certified), then we can.
I'm not sure if the following meta-commands are required. I have them listed as required, but don't know if this is correct. Can someone please confirm or deny?
!KEYWORDS
!CATEGORY
Here it is:
Proposed changes to the LDraw part header to support the Contributor
Agreement - Version 5
The following shortcomings in the current LDraw part header require
attention to support the Contributor Agreement :
a) The author line fails to identify the LDraw.org username – the basis upon which CA affirmation is assessed.
b) The header does not identify whether the part is covered by the Contributor Agreement or not.
c) The change history comment lines are unstructured and fail to clearly identify the LDraw.org username.
d) The header does not conform to the new meta command syntax. (Only acceptable to partially correct this.)
e) The header fails to clearly identify unofficial parts.
f) The header fails to clearly separate the header section from the file content. (Removed by Travis based on Steve's advice. We can of course change our mind on this.)
The proposed new structure for official parts is :
-------------------Beginning of Proposal-------------------
0 PartDescription
0 Name: Filename.dat
0 Author: RealName [UserName]
0 !LDRAW_ORG Part|Subpart|Primitive|48_Primitive UPDATE YYYY-RR
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt or
0 !LICENSE Not redistributable : see NonCAreadme.txt
0 !HELP Optional free text description of file usage
0 !HELP Second row after user's line break to simulate paragraph
0 BFC ( CERTIFY ( CCW | CW ) | NOCERTIFY )
0 !CATEGORY Category name
0 !KEYWORDS words, more words,…,
0 !KEYWORDS words in second row, …, final words
0 !CMDLINE LDraw run-time command(s)
0 !HISTORY YYYY-MM-DD [UserName] Free text description of change
0 // Second row simulating formatting
or
0 !HISTORY YYYY-MM-DD {RealName} Free text description of change
0 // Comments
1 <colour> x y z a b c d e f g h i <file>
Where
PartDescription is the descriptive name of the part (limited to 64 characters)
Filename is the file name
RealName is the author's real name
UserName is the author's LDraw username. It needs to be optional for those past authors that don't have a PT username
YYYY-RR is the LDraw update year and release within year
The square brackets are included in the file to indicate LDraw usernames.
The following meta-commands are optional:
!HELP
!CMDLINE
BFC (It is highly recommended to include this statement with a NOCERTIFY for non-BFC certified parts, but not required.)
All other meta-commands above are mandatory. No other meta-commands are allowed in the part header.
For example:
0 Animal Scorpion
0 Name: 30169.dat
0 Author: Chris Dee [cwdee]
0 !LDRAW_ORG Part UPDATE 2006-01
0 !LICENSE Redistributable under CCAL version 2.0 : see CAreadme.txt
0 !HELP Obviously there is no need for additional
0 !HELP information in this part. But it will give
0 !HELP you an idea of the primitive formatting.
0 !HELP
0 !HELP And probably we should limit the length of
0 !HELP a line to 40 – 50 characters for the sake of readability.
0 BFC CERTIFY CW
0 !CATEGORY Animal
0 !KEYWORDS Sting, Poison, Adventurers, Egypt
0 !KEYWORDS Zodiac
0 !CMDLINE –c1
0 !HISTORY 2000-08-?? {Axel Poque} fixes to resolve L3P error messages
0 !HISTORY 2000-08-?? {Manfred Moolhuysen} fixes to resolve L3P error messages,
0 // fixed gap where body meets head
0 !HISTORY 2002-04-25 [PTadmin] Official update 2002-02
0 !HISTORY 2004-05-18 [guyvivan] Made BFC compliant
0 !HISTORY 2004-05-18 [guyvivan] Use more primitive
0 !HISTORY 2006-??-?? [PTadmin] Official update 2006-01
0 // Tail
1 16 1 0 23 1 0 0 0 1 0 0 0 1 4-4cyli.dat
or
0 Boat Base 8 x 10
0 Name: 2622.dat
0 Author: Chris Alano
0 !LDRAW_ORG Part UPDATE 2000-02
0 !LICENSE Not redistributable : see NonCAreadme.txt
0 BFC NOCERTIFY
0 !CATEGORY Boat
0 !KEYWORDS Pirates, Caribbean, Ship
2 24 100 24 80 80 24 20
-------------------End of Proposal-------------------
The following are Willy's comments from version 4. In the interest of getting the CA-approved library out the door, I'd like to request that we postpone any discussion about the below points (with the exception of the ~Moved to bit in bold). They're good points, but don't require updates to all existing files. As such, they can be implemented at any time. As for the ~Moved to suggestion, we need to decide now if we should do this. Please comment.
I'd also like the release process to automatically add lines to this
when a part is made official – at present it is unclear which changes
are included in which version of the file.
I also propose to add full headers to the ~Moved to files and other
admin generated files with a special name / username, probably "PTadmin".
As Travis pointed out the header fails to clearly identify if the file
is a part, especially when they are at the PT. I therefore suggest to
modify the !LDRAW_ORG statement for PT-usage only as following:
0 !LDRAW_ORG Unofficial_Part| Unofficial_Subpart| Unofficial_Primitive
|Unofficial_48_Primitive
A syntax like "Unofficial Part", "Subpart_unofficial",
"Unofficial_Element", "Non-official Part" would be rejected by the PT.
0 !HISTORY 2006-05-22 [PTadmin] Initial version
0 !HISTORY 2006-08-01 [PTadmin] Official update 2006-02
0 !HISTORY 2006-08-22 [Holly-Wood] Sum up of the current discussion,
added unofficial statement,
0 !HISTORY 2006-08-22 [Holly-Wood] added exclamation mark, added
keywords and category, made BFC compliant
0 !HISTORY 2006-08-23 [Holly-Wood] version 4. removed pre-character !
from BFC statement, added HELP meta-
--Travis
------------------------------------------------------------------------------
_______________________________________________
LSC mailing list
LSC at ldraw.org
http://five.pairlist.net/mailman/listinfo/lsc
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://five.pairlist.net/pipermail/lsc/attachments/20060901/92b6aa25/attachment-0001.htm
More information about the LSC
mailing list