Hi Tim,
So if we try simplifying this with the UNI Unicode File spec, then is the
following acceptable?
Cheers,
Larry
Update Definition of <Token> in section 2.1 Extended Backus-Naur Form (EBNF)
<HexDigitU> ::= (\ua-\uf\uA-\uF\u0-\u9)
<Token> ::= <CtrlChar> <MS> L"string" <MS>
<Identifier>(\uA-\uZ\ua\uz)(\uA-\uZ\ua\uz\u0-\u9\u_)*
<Identifier> ::= (\uA-\uZ\ua\uz)(\uA-\uZ\ua\uz\u0-\u9\u_)*
<LangCode> ::= <RFC4646>
Add the following chapter.
3
Meta-Data UNI Files
In order to support distributions conforming to the UEFI PI Distribution
Package Specification, Unicode files may be used to contain localization
content passed along in the XML file for content that cannot be passed using
ASCII characters.
The format of the Unicode files that contain the optional Module and Package
localization content for distribution is as follows:
<MetaInfoFile> ::= <CommentLine>*
<MetaData>+
<MetaData> ::= {<CommentLine>} {<BlankLine>} {<UnicodeLines>}
Additional Definitions used for Package Meta-Data Token Identifiers
<ErrorNumber> ::= (\u0-\u9\ua-\uf\uA-\uF)
<PcdName> ::= <CName> L"_" <CName>
<CName> ::= (\uA-\uZ\ua-\uz)(\uA-\uZ\ua-\uz\u0-\u9)*
Refer to Chapter 2.1, Unicode Strings File Format, Extended Backus-Naur Form
(EBNF) for the definitions of CommentLine, BlankLine and UnicodeLines.
It is also recommended that the comment section at the start of the file use
content consistent with content described for meta-data headers, including a
start tag line, L"// @file", and include an abstract, description, copyright
and license information.
3.1 Module Meta-Data
If a Module's INF file contains a MODULE_UNI_FILE entry in its [Defines]
section, then that Unicode file may contain localization of the Module's
Abstract and Description lines.
The Intel UEFI Packaging Tool, UPT, provided as part of the EDK II BaseTools
will use following identifiers in the UnicodeLines' Token element to pass along
localization of the Module's Abstract and Description. This file is created
from the UEFI PI Distribution Package XML content by the Intel UEFI Packaging
Tool during installation, and will be read from the file into the UEFI PI
Distribution Package XML when creating a distribution.
L"STR_MODULE_ABSTRACT"
L"STR_MODULE_DESCRIPTION"
If a Module's INF file contains a Unicode file entry in its
[UserExtensions.TianoCore."ExtraFiles"] section, then that Unicode file may
contain a localized version of a User Interface name for the module as well as
other content. This file is used to hold content that is not required by UEFI
PI Distribution Package, but may be useful for User Interface tools. The
following identifier may be used in the UnicodeLines' Token element to pass
along the User Interface name of the module.
L"STR_PRORPERTIES_MODULE_NAME"
Other content may be provided in this file as the file itself will be carried
along with the Module in a UEFI PI Distribution Package.
3.1 Package Meta-Data
If a Package's DEC file contains a PACKAGE_UNI_FILE entry in its [Defines]
section, then that Unicode file may contain localization of the Package's
Abstract and Description line as well as information used for PCD declarations.
This file is created from the UEFI PI Distribution Package XML content by the
Intel UEFI Packaging Tool during installation, and will be read from the file
into the UEFI PI Distribution Package XML when creating a distribution.
The following identifiers are used in the UnicodeLines' Token element to pass
along localization of the Package's Abstract and Description.
L"STR_PACKAGE_ABSTRACT"
L"STR_PACKAGE_DESCRIPTION"
The following describes the format for an identifier used in the UnicodeLines'
Token element to pass along localization of a TokenSpaceGuid's Error messages
that are referenced by an error number. The CName is the Token Space GUID's C
Name declared in the DEC file's [Guids] section.
L"STR_" <CName> "_ERR_" <ErrorNumber>
The following describes the format for an identifier used in the UnicodeLines'
Token element to pass along localization of a PCD's HELP and PROMPT content.
L"STR_" <PcdName> "_HELP"
L"STR_" <PcdName> "_PROMPT"
If a Package's DEC file contains a Unicode file entry in its
[UserExtensions.TianoCore."ExtraFiles"] section, then that Unicode file may
contain a localized version of a User Interface name for the package as well as
other content. This file is used to hold content that is not required by UEFI
PI Distribution Package, but may be useful for User Interface tools. The
following identifier may be used in the UnicodeLines' Token element to pass
along the User Interface name of the package.
L"STR_PRORPERTIES_MODULE_NAME"
Other content may be provided in this file as the file itself will be carried
along with the Package in a UEFI PI Distribution Package.
From: Tim Lewis [mailto:[email protected]]
Sent: Tuesday, August 12, 2014 3:46 PM
To: Hauch, Larry
Cc: [email protected]
Subject: RE: EDK II UNI Unicode File Specification Update
Larry -
As a tools developer and a QA team, we (Insyde) can tell you that the existing
EBNF is hard to manage. We have rewritten it to be readable by tools and by
humans. When you start having conditions in the grammar (see the INF spec,
section 3.2), you know you've definitely crossed the line.
I think the core items, like Expressions and PCDs can be defined in the EDK2
Build Specification. I think that the Expression syntax could be there also, in
an appendix. The PCD syntax is not shared, so we'd parcel that out to the
relevant .fdf/.inf/.dsc/.dec specifications but refer back to the Build spec
for definition for common terms.
Tim
From: Hauch, Larry [mailto:[email protected]]
Sent: Tuesday, August 12, 2014 3:22 PM
To: Tim Lewis
Cc: [email protected]<mailto:[email protected]>
Subject: RE: EDK II UNI Unicode File Specification Update
Hi Tim,
I agree that the EBNF is getting cumbersome and we should really look at
reducing this.
I need to work with my internal development and validation teams (who keep
asking for more EBNF) to figure out a better method.
Our validation team has expressed the desire to have everything in one place so
that they can only look at the EBNF and not have to look at anything else.
I agree that we would be better served if we could centralize some of the
documentation so that we update the PCD document to contain all of the relevant
information to a PCD document and then have the other specs refer to
appropriate chapters in the other documents. (I was attempting to do that with
the EDK II Meta-Data Expression Spec document which I hope to publish shortly -
newer versions of the EDK II INF/DEC/DSC/FDF specs will have the expression
EBNF removed and a reference to the Expression Spec.).
Cheers,
Larry
From: Tim Lewis [mailto:[email protected]]
Sent: Monday, August 11, 2014 3:03 PM
To: [email protected]<mailto:[email protected]>
Subject: Re: [edk2] EDK II UNI Unicode File Specification Update
It is about using EBNF for specific string-token name patterns. In cases where
the basic pattern is X = Y (as described in the overview portions of the same
spec) the grammar is much simpler and easier to ready if it says <TS>
Identifier <TS> "=" <TS> Value. The question: "which X is valid" and "which Y
is valid for which X" is easily taken care of in the sections.
Again, this is speaking as another company has worked valiantly to create tools
compatible with the EDK2 toolset, and to teach the grammar to new engineers.
On the other topic, we would be willing to contribute changes on specific
documents, such as the Build Specification. Do you think it is better to
describe such topics as PCDs where they are defined (.DEC spec) or as a general
build concept (Build spec)?
Tim
From: Kinney, Michael D [mailto:[email protected]]
Sent: Monday, August 11, 2014 12:27 PM
To: [email protected]<mailto:[email protected]>
Subject: Re: [edk2] EDK II UNI Unicode File Specification Update
Hi Tim,
Thanks for the feedback on this topic. We have had similar discussions over
the last couple of days for where this content should be listed.
These updates do reserve specific string token name patterns. Whenever we have
used specific keywords in syntax in the other EDK II related documents, the
keywords have been added as part of the grammar using an EBNF description.
This provides clear direction for tool development and tool validation. Is
your feedback about the location of this content, or the use of EBNF to for the
string token name patterns?
Thanks,
Mike
From: Tim Lewis [mailto:[email protected]]
Sent: Monday, August 11, 2014 11:23 AM
To: [email protected]<mailto:[email protected]>
Subject: Re: [edk2] EDK II UNI Unicode File Specification Update
Larry -
I would recommend that these sort of changes not be added to the grammar, but
rather in the specification text related to the [UserDefined] or DEFINES
section of the .inf or .dec specification.
Tim
From: Hauch, Larry [mailto:[email protected]]
Sent: Monday, August 11, 2014 10:56 AM
To: [email protected]<mailto:[email protected]>
Subject: [edk2] EDK II UNI Unicode File Specification Update
Hi Folks,
The following is content we would like to add to the EDK II UNI Unicode File
Specification to support the changes we have proposed for supporting
localization in EDK II that can be consumed by the packaging to when creating a
UEFI PI Distribution Package (and when installing a UEFI PI Distribution
Package using the EDK II upt tool).
Please respond with feedback the end of this week.
Thanks,
Larry
3
UNI File Common Content
This section defines the common tag syntax for content in a Unicode file
specified in the following Module and Package UNI sections.
Prototype
<US> ::= L" "
<MS> ::= <US>+
<ME> ::= {<MS>} {<EOL>}
<CR> ::= 0x000D
<LF> ::= 0x000A
<EOL> ::= <CR><LF>
<BlankLine> ::= <EOL>
<PChars> ::= (0x0020-0xF6FF)
<LangCode> ::= <RFC4646>
<RFC4646> ::= (\ua-\uz\uA-\uZ){2,8}
[L"-" (\ua-\uz\uA-\uZ\u0-\u9){2,8}]
<UDblQuote> ::= 0x0022
<String> ::= <UDblQuote> <PChars>* <UDblQuote>
<Header> ::= L"// /** @file" <EOL>
[<Abstract> <EOL>]?
[L"//" <EOL>]+
[<Description> <EOL>]*
[L"//" <EOL>]
[<Copyright> <EOL>]+
[L"//" <EOL>]*
[<License> <EOL>]+
[L"//" <EOL>]*
L"// **/" <EOL>+
<Abstract> ::= L"//" <MS> <PChars>+
<Description> ::= L"//" <MS> <PChars>+
<Copyright> ::= L"//" <MS> "Copyright (c)" <MS> <Date>
<Date> ::= {<Year>} {<YearRange>} {<YearList>} L"," <US> <Comp>
<Year> ::= (\u2-\u9) (\u0-\u9){3}
<YearRange> ::= <Year> <US> L"-" <US> <Year>
<YearList> ::= <Year> ["," <US> <Year>]+
<Comp> ::= <PChars>* L"." <MS> L"All rights reserved.<BR>"
<License> ::= L"//" <MS> <PChars>*
<LangEntry> ::= L"#language" <MS> <LangCode> <ME>
[<String> <ME>]+
4
MODULE_UNI_FILE Content
This section defines the tag syntax for content in a Unicode file specified in
the MODULE_UNI_FILE entry of an INF file's [Defines] section.
Prototype
<InfUnicodeFile> ::= <Header>
<BlankLine>*
<AbstractTag>?
<BlankLine>*
<DescriptionTag>?
<BlankLine>*
<AbstractTag> ::= L"#string" <MS> L"STR_MODULE_ABSTRACT" <ME>
<LangEntry>+
<DescriptionTag> ::= L"#string" <MS> L"STR_MODULE_DESCRIPTION" <ME>
<LangEntry>+
Example
// /** @file
// TerminalDxe Module Localized Abstract and Description Content
//
// Copyright (c) 2012 - 2014, Intel Corporation. All rights reserved.<BR>
//
// This program and the accompanying materials
// are licensed and made available under the terms and conditions of the BSD
// License which accompanies this distribution.
// The full text of the license may be found at
// http://opensource.org/licenses/bsd-license.php
// THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
// WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
//
// **/
#string STR_MODULE_ABSTRACT
#language en-US
"Terminal module installs Simple Text Input(ex)/Out protocols for serial "
"devices."
#string STR_MODULE_DESCRIPTION #language en-US
"This module will install Simple Text Input (Ex) protocol and Simple Test "
"Output protocols based on Serial I/O protocol for serial devices including "
"hotplug serial devices."
5
Module Extra File Content
This section defines the tag syntax for content in a Unicode file specified in
an extra file specified in a [UserExtensions.TianoCore."ExtraFiles"] section of
an INF file.
Prototype
<InfUnicodeFile> ::= <Header>
<BlankLine>*
<PropertyName>?
<BlankLine>*
<PropertyName> ::= L"#string" <MS>
L"STR_PROPERTIES_MODULE_NAME" <ME>
<LangEntry>+
Example
// /** @file
// TerminalDxe Localized Strings and Content
//
// Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>
//
// This program and the accompanying materials
// are licensed and made available under the terms and conditions of
// the BSD License which accompanies this distribution. The full text
// of the license may be found at
// http://opensource.org/licenses/bsd-license.php
// THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS"
// BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER
// EXPRESS OR IMPLIED.
//
// **/
#string STR_PROPERTIES_MODULE_NAME
#language en-US
"Terminal DXE Driver"
6
PACKAGE_UNI_FILE Content
This section defines the tag syntax for content in a Unicode file specified in
the PACKAGE_UNI_FILE entry of a DEC file's [Defines] section.
Prototype
<DecUnicodeFile> ::= <Header>
<BlankLine>*
<AbstractTag>?
<BlankLine>*
<DescriptionTag>?
<BlankLine>*
<PcdErrorTags>*
<BlankLine>*
<PcdHelpTags>*
<BlankLine>*
<PcdPromptTags>*
<BlankLine>*
<AbstractTag> ::= L"#string" <MS>
L"STR_PACKAGE_ABSTRACT" <ME>
<LangEntry>+
<DescriptionTag> ::= L"#string" <MS>
L"STR_PACKAGE_DESCRIPTION" <ME>
<LangEntry>+
<ENO> ::= (\u0-\u9\ua-\uf\uA-\uF){8}
<PcdErrorTags> ::= L"#string" <MS>
L"STR_" <Tsp> L"_ERR_" <ENO> <ME>
<LangEntry>+
<Tsp> ::= <TokenSpaceGuidCName>
<PcdName ::= <CName>
<TokenSpaceGuidCName> ::= <CName>
<PCD> ::= <TokenSpaceGuidCName> L"_" <PcdName>
<CName> ::= (\ua-\uz\uA-\uZ) (\ua-\uz\uA-\uZ\u0-\u9)*
<PcdHelpTags> ::= L"#string" <MS> L"STR_" <PCD> L"_HELP" <ME>
<LangEntry>+
<PcdPromptTags> ::= L"#string" <MS> L"STR_" <PCD> L"_PROMPT" <ME>
<LangEntry>+
Example
// /** @file
// Package help, error and prompt strings.
//
// Copyright (c) 2013 - 2014, Intel Corporation. All rights reserved.<BR>
//
// This program and the accompanying materials are licensed and made available
// under the terms and conditions of the BSD License which accompanies this
// distribution.
// The full text of the license may be found at
// http://opensource.org/licenses/bsd-license.php
//
// THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
// WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
//
// **/
#string STR_PACKAGE_ABSTRACT
#language en-US
"This package provides network modules that conform to UEFI 2.2 specification."
#string STR_PACKAGE_DESCRIPTION
#language en-US
"This package provides network modules that conform to UEFI 2.2 specification."
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecCertificateEnabled_PROMPT
#language en-US
"Enable IPsec IKEv2 Certificate Authentication."
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecCertificateEnabled_HELP
#language en-US
"Indicates if the IPsec IKEv2 Certificate Authentication feature is enabled or
not.<BR><BR>"
"TRUE - Certificate Authentication feature is enabled.<BR>"
"FALSE - Does not support Certificate Authentication.<BR>"
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCaFile_PROMPT
#language en-US
"CA file."
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCaFile_HELP
#language en-US
"CA certificate used by IPsec."
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCaFileSize_PROMPT
#language en-US
"CA file's size."
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCaFileSize_HELP
#language en-US
"CA certificate file's size."
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificate_PROMPT
#language en-US
"Pubic Key for remote peer."
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificate_HELP
#language en-US
"X509 certificate as Public Key which is used by IPsec (DER format)"
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificateSize_PROMPT
#language en-US
"Pubic Key's size."
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificateSize_HELP
#language en-US
"X509 certificate as Public Key's size."
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificateKey_PROMPT
#language en-US
"Private Key."
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificateKey_HELP
#language en-US
"Private Key used by IPsec (PEM format)."
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificateKeySize_PROMPT
#language en-US
"Private Key's size."
#string STR_gEfiNetworkPkgTokenSpaceGuid_PcdIpsecUefiCertificateKeySize_HELP
#language en-US
"Private Key's size."
7
Package Extra File Content
This section defines the tag syntax for content in a Unicode file specified in
the entry of a DEC file's [UserExtensions.TianoCore. "ExtraFiles"] section.
Prototype
<DecUnicodeFile> ::= <Header>
<BlankLine>*
<PropertyName>?
<PropertyName> ::= L"#string" <MS>
L"STR_PROPERTIES_PACKAGE_NAME" <ME>
<LangEntry>+
Example
// /** @file
// Network Package Localized Strings and Content.
//
// Copyright (c) 2013 - 2014, Intel Corporation. All rights reserved.<BR>
//
// This program and the accompanying materials are licensed and made available
// under the terms and conditions of the BSD License which accompanies this
// distribution.
// The full text of the license may be found at
// http://opensource.org/licenses/bsd-license.php
//
// THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
// WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
//
// **/
#string STR_PROPERTIES_PACKAGE_NAME
#language en-US
"Network package"
Larry Hauch
Intel Corporation
SSG, STO, Platform Software Infrastructure
2800 Center Dr.
DuPont, WA 98327
Work: (253) 371-8550
------------------------------------------------------------------------------
_______________________________________________
edk2-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/edk2-devel
