OpenCascade/occt
1
0
Fork 0
mirror of https://git.dev.opencascade.org/repos/occt.git synced 2025-04-16 10:08:36 +03:00
Code

0031985: Documentation - description of TDocStd_FormatVersion is excessive

Browse Source 
Description of TDocStd_FormatVersion enum is simplified and formatting for good rendering in HTML
This commit is contained in:
vro 2020-12-09 12:08:40 +03:00 committed by bugmaster
parent c22b52d60e
commit 65cec1a6ef
1 changed files with 37 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
src/TDocStd/TDocStd_FormatVersion.hxx
View File

@ -15,70 +15,55 @@
#define _TDocStdFormatVersion_HeaderFile #define _TDocStdFormatVersion_HeaderFile
//! Storage format versions of OCAF documents in XML and binary file formats. //! Storage format versions of OCAF documents in XML and binary file formats.
//!
//! Reading of new documents by old applications. //! OCAF document file format evolves and a new version number indicates each improvement of the format.
//! Open CASCADE Technology evolves and file format of OCAF document evolves too. Does it mean that an application based on an old version of Open CASCADE Technology //! This enumeration lists all versions of an OCAF document. TDocStd_FormatVersion_CURRENT value refers to the last file format version.
//! cannot read an OCAF document saved by an application using a newer version of Open CASCADE Technology? //! By default, Open CASCADE Technology writes new documents using the last file format version.
//! Let us consider this question in detail and see when it is possible. //! The last version of Open CASCADE Technology is able to read old documents of any version.
//! Storage version of OCAF document is stored in TDocStd_Document class and accessible via StorageFormatVersion() method. //! However, a previous version of Open CASCADE Technology may not be able to read a new document.
//! In order to change it, call the method ChangeStorageFormatVersion(). In order to save a document in older version //! In this case use the method ChangeStorageFormatVersion() from TDocStd_Document to change the file format version.
//! (corresponding to an earlier version of Open CASCADE Technology), //! Then, save the document by means of SaveAs() from TDocStd_Application.
//! change the storage version (by means of TDocStd_Document::ChangeStorageFormatVersion()) and save the document(via TDocStd_Application::SaveAs()). //!
//! It will be stored using the rules of an old version of Open CASCADE Technology. //! If it is necessary to improve an XML or binary file format of OCAF document, follow please the next steps:
//! What to do if you need to improve the file format of an OCAF document, and in the same time, //! - increment the file format version in this enumeration. Put a reference to the last file format version by means of TDocStd_FormatVersion_CURRENT.
//! you would like the current application already sent to the users to read the new documents? //! - introduce the improvement in OCAF attribute storage and retrieval drivers, if necessary.
//! Here it is an example of a similar case, which might give you an idea how to implement it. //! As an example, please consider the file XmlMDataStd_TreeNodeDriver.cxx.
//! Example. //! - test the improvement on current file format version and on the previous one.
//! In order to improve speed of writing and reading of OCAF document in XML file format a developer decided to perform the following improvements in OCAF:
//! - Removal of GUID of a TDataStd_TreeNode attribute, if it is default. Indeed, it seems reasonable not to write a GUID into XML file if it is default.
//! It derceases size of file and speeds-up writing and reading of the file. The same approach concerns several other attributes with default GUIDs.
//! - Compression of TDataStd_ExtStringArray attribute. It uses a new line for each value of the array abbreviated by XML tags.
//! If all values were put into one line separated by a comma or any other separator, it would decrease the file size, speed-up reading and writing.
//! It is obvious that an old application, which does not know about an opportunity for a TDataStd_TreeNode attribute to have no GUID in XML file,
//! may fail to read such an improved XML file. It means that we should 'teach' Open CASCADE Technology of later versions to write document in an old format. How to do it?
//! - First, we increase the storage format version of the document (in this TDocStd_FormatVerison.hxx file).
//! - Then, we introduce a code in XmlMDataStd_TreeNodeDriver::Paste(), which checks the document storage version and if it is one of the previous versions,
//! it writes the GUID in any case (in spite of it is default).
//! - For a TDataStd_ExtStringArray we do the same : we check the document storage version and if it is one of the previous versions,
//! we write values of the array in old manner : one per line surrounding each value by XML tags.
//! For details, please see XmlMDataStd_ExtStringArrayDriver::Paste().
//! This way we obtain an opportunity to save OCAF document in an old file format, while for new applications we keep an improvement
//! (smaller files on disk, reading and writing of the XML files is faster).
enum TDocStd_FormatVersion enum TDocStd_FormatVersion
{ {
TDocStd_FormatVersion_VERSION_2 = 2, //!< First supported version TDocStd_FormatVersion_VERSION_2 = 2, //!< First supported version
TDocStd_FormatVersion_VERSION_3, //!< (OCCT 6.3.0) TDocStd_FormatVersion_VERSION_3, //!< OCCT 6.3.0
//!< XML: Adding DeltaOnModification functionality to set of Standard attributes [#0019403] //!< * XML: Adding DeltaOnModification functionality to set of Standard attributes [#0019403]
//!< BIN: Add Delta to numbers data, changes in ShapeSection [#0019986, #0019403] //!< * BIN: Add Delta to numbers data, changes in ShapeSection [#0019986, #0019403]
TDocStd_FormatVersion_VERSION_4, //!< (OCCT 6.3.1) TDocStd_FormatVersion_VERSION_4, //!< OCCT 6.3.1
//!< XML: Naming mechanism improvement [#0021004] //!< * XML: Naming mechanism improvement [#0021004]
//!< BIN: entry, ContextLabel for tree [#0021004] //!< * BIN: entry, ContextLabel for tree [#0021004]
TDocStd_FormatVersion_VERSION_5, //!< (OCCT 6.3.1) TDocStd_FormatVersion_VERSION_5, //!< OCCT 6.3.1
//!< XML: Separation of OCAF to Lite and Standard parts completion [#0021093] //!< * XML: Separation of OCAF to Lite and Standard parts completion [#0021093]
//!< BIN: Convert old format to new [#0021093] //!< * BIN: Convert old format to new [#0021093]
TDocStd_FormatVersion_VERSION_6, //!< (OCCT 6.5.0) TDocStd_FormatVersion_VERSION_6, //!< OCCT 6.5.0
//!< XML: Add location [#0022192] //!< * XML: Add location [#0022192]
//!< BIN: Add location [#0022192] //!< * BIN: Add location [#0022192]
TDocStd_FormatVersion_VERSION_7, //!< (OCCT 6.7.0) TDocStd_FormatVersion_VERSION_7, //!< OCCT 6.7.0
//!< XML: Add orientation [#0023766] //!< * XML: Add orientation [#0023766]
//!< BIN: Add orientation, type migration [#0023766] //!< * BIN: Add orientation, type migration [#0023766]
TDocStd_FormatVersion_VERSION_8, //!< (OCCT 7.0.0) TDocStd_FormatVersion_VERSION_8, //!< OCCT 7.0.0
//!< XML: Replace TPrsStd_AISPresentation attribute with TDataXtd_Presentation [#0026290] //!< * XML: Replace TPrsStd_AISPresentation attribute with TDataXtd_Presentation [#0026290]
//!< BIN: Stop convert old format [#0026290] //!< * BIN: Stop convert old format [#0026290]
TDocStd_FormatVersion_VERSION_9, //!< (OCCT 7.1.0) TDocStd_FormatVersion_VERSION_9, //!< OCCT 7.1.0
//!< BIN: Add GUIDs, Process user defined guid [#0027932] //!< * BIN: Add GUIDs, Process user defined guid [#0027932]
TDocStd_FormatVersion_VERSION_10, //!< (OCCT 7.2.0) TDocStd_FormatVersion_VERSION_10, //!< OCCT 7.2.0
//!< BIN: ReadTOC changed to handle 64-bit file length [#0028736] //!< * BIN: ReadTOC changed to handle 64-bit file length [#0028736]
TDocStd_FormatVersion_CURRENT = TDocStd_FormatVersion_VERSION_10 //!< The latest version. TDocStd_FormatVersion_CURRENT = TDocStd_FormatVersion_VERSION_10 //!< The latest version
}; };
#endif // _TDocStdFormatVersion_HeaderFile #endif // _TDocStdFormatVersion_HeaderFile