# Definition IFC - Markdown and Version Control

**URL:** <https://forums.buildingsmart.org/t/definition-ifc-markdown-and-version-control/1774>\
**Category:** IfcDoc Tool\
**Created:** [September 3, 2019, 2:16am UTC](https://forums.buildingsmart.org/t/definition-ifc-markdown-and-version-control/1774 "2019-09-03T02:16:31Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![jonm](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/jonm/32/16_2.png) [@jonm](https://forums.buildingsmart.org/u/jonm)\
**Post date:** [September 3, 2019, 2:16am UTC](https://forums.buildingsmart.org/t/definition-ifc-markdown-and-version-control/1774/1 "2019-09-03T02:16:31Z")

</div>

I’ve been working for a while on the back end of IfcDoc, in particular relating to serializing and deserializing the data model used to store the definition of IFC (including documentation). This is particularly for the use case of version control, so that simultaneous efforts to improve IFC can be conducted and the resultant changes merged and tracked.

We have been using git for version control, and part of this work has been the conversion of documentation being stored in html format to markdown.  
You can see an example here or markdown documentation:

> <https://github.com/buildingSMART/IFC/blob/master/Sections/Resource%20definition%20data%20schemas_16GWp8yon3heQ2MIJBE0uz/Schemas/IfcGeometryResource_3yM49UJkz0wAIY90iB17Th/Entities/IfcCircle/Documentation.md>

Click on the edit button and you can see the markdown plain text.  
This can then generate documentation such as [https://standards.buildingsmart.org/IFC/RELEASE/IFC4\_1/FINAL/HTML/link/ifccircle.htm](https://standards.buildingsmart.org/IFC/RELEASE/IFC4_1/FINAL/HTML/link/ifccircle.htm)

This work is still subject to review and testing, so please consider this prior to making forks with significant changes.

You can see some typos I fixed here: [https://github.com/buildingSMART/IFC/commit/360d03d8b6b2cda9806c63027990b0c4714496e2](https://github.com/buildingSMART/IFC/commit/360d03d8b6b2cda9806c63027990b0c4714496e2)

One of the next tests could be to add a branch for road draft and start merging changes.

I’ve pushed the changes to IfcDoc to make this work to this branch [https://github.com/buildingSMART/IfcDoc/tree/Markdown](https://github.com/buildingSMART/IfcDoc/tree/Markdown)

I’ll build the exe if anyone wants to try that and can’t build it.

---

<div class="post-metadata">

**Author:** ![Moult](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/moult/32/196_2.png) [@Moult](https://forums.buildingsmart.org/u/Moult)\
**Post date:** [September 3, 2019, 2:27am UTC](https://forums.buildingsmart.org/t/definition-ifc-markdown-and-version-control/1774/2 "2019-09-03T02:27:22Z")

</div>

Beautiful work, @jonm !

---

<div class="post-metadata">

**Author:** ![jonm](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/jonm/32/16_2.png) [@jonm](https://forums.buildingsmart.org/u/jonm)\
**Post date:** [September 3, 2019, 8:47pm UTC](https://forums.buildingsmart.org/t/definition-ifc-markdown-and-version-control/1774/3 "2019-09-03T20:47:54Z")

</div>

Thanks Dion.

Having tested and used the repository a bit, I’d like to flush it and recreate it one more time (hopefully the last). Here’s what I’d like to change.

Remove the global ids from as many folder paths as possible. This was implemented for uniqueness but we could define a rule that concepts at a folder level have to have a unique name. Concepts such as properties and quantities would retain the global id.

ie

> <https://github.com/buildingSMART/IFC/blob/master/Sections/Resource%20definition%20data%20schemas_16GWp8yon3heQ2MIJBE0uz/Schemas/IfcGeometryResource_3yM49UJkz0wAIY90iB17Th/Entities/IfcCircle/Documentation.md>

would become

[https://github.com/buildingSMART/IFC/blob/master/Sections/Resource%20definition%20data%20schemas/Schemas/IfcGeometryResource/Entities/IfcCircle/Documentation.md](https://github.com/buildingSMART/IFC/blob/master/Sections/Resource%20definition%20data%20schemas/Schemas/IfcGeometryResource/Entities/IfcCircle/Documentation.md)

We could potentially expand out model view concepts into their own folders if we implement this without hitting long path problems.

Second thing I’d like to change is to repath images to relative and calculate the html path when publishing. (thanks @aothms for showing me how this works) This would mean they would render correctly in github. Ie [https://github.com/jmirtsch/IFC/blob/master/Sections/Resource%20definition%20data%20schemas\_16GWp8yon3heQ2MIJBE0uz/Schemas/IfcGeometryResource\_3yM49UJkz0wAIY90iB17Th/Entities/IfcCircle/Documentation.md](https://github.com/jmirtsch/IFC/blob/master/Sections/Resource%20definition%20data%20schemas_16GWp8yon3heQ2MIJBE0uz/Schemas/IfcGeometryResource_3yM49UJkz0wAIY90iB17Th/Entities/IfcCircle/Documentation.md)

 ![190904%20circle%20with%20images](https://us1.discourse-cdn.com/flex016/uploads/buildingsmart1/original/1X/7a45c8c6ecff7103589501415b9033c0a84615b9.png)

instead of

 ![190904%20circle%20markdown%20without%20images](https://us1.discourse-cdn.com/flex016/uploads/buildingsmart1/original/1X/cc31aaeeabb9d2d44a151019d598ed4786445b3a.png)

I’d like to either remove of expand out attributes specific to the definition of a concept. For example, localizations could be moved into a sub folder so it’s clearer when a localization changed rather than the definition of a concept. This will have an effect on processing time due to the extra folders. I’d personally like to remove the diagram definitions as this creates a lot of change noise. But I either need to refactor the way they are stored and referenced so they aren’t nested into the concept, or we need to automate their creation. For the time being, I’d nominate the former.

If anyone else has suggestions, I look forward to hearing them.

---

<div class="post-metadata">

**Author:** ![TLiebich](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/tliebich/32/71_2.png) [@TLiebich](https://forums.buildingsmart.org/u/TLiebich)\
**Post date:** [September 4, 2019, 9:51am UTC](https://forums.buildingsmart.org/t/definition-ifc-markdown-and-version-control/1774/4 "2019-09-04T09:51:25Z")

</div>

great work. Having the figures showing inline is a great improvement. I would support to move all additional information (like translations, the snippets to place the express-g graphics, etc.) out, to separate the normative part from additional information.

Given that we might want to change the graphical representation of the IFC schema (most likely to UML) it would be another argument to move the graphic lines out of the normative text, so that a later mass change would not create a complete set of change notifications for each type and entity.

---

<div class="post-metadata">

**Author:** ![ReD\_CoDE](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/red_code/32/226_2.png) [@ReD\_CoDE](https://forums.buildingsmart.org/u/ReD_CoDE)\
**Post date:** [September 4, 2019, 10:11am UTC](https://forums.buildingsmart.org/t/definition-ifc-markdown-and-version-control/1774/5 "2019-09-04T10:11:18Z")

</div>

I think Jon is in a right path. His effort will cause we all have all schema content in a way that has the ability to improve them or build them again from scratch.

If we want develop IFC schema based on UML (UML 2) we need develop them from scratch

I think it’d be good to check CityGML and their approach which is more advanced than current approach in IFC schema and even IFD

---

<div class="post-metadata">

**Author:** ![TLiebich](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/tliebich/32/71_2.png) [@TLiebich](https://forums.buildingsmart.org/u/TLiebich)\
**Post date:** [September 4, 2019, 10:17am UTC](https://forums.buildingsmart.org/t/definition-ifc-markdown-and-version-control/1774/6 "2019-09-04T10:17:05Z")

</div>

just to be explicit - there is no plan to develop IFC from scratch using UML. There is a method in place to convert current IFC EXPRESS source into XMI to be visualized (and eventually edited) in UML (UML tool, like Enterprise Architect). So UML class diagrams could be an alternative graphical representation, replacing (or accompaning) the current EXPRESS-G graphical representation.

---

<div class="post-metadata">

**Author:** ![ReD\_CoDE](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/red_code/32/226_2.png) [@ReD\_CoDE](https://forums.buildingsmart.org/u/ReD_CoDE)\
**Post date:** [September 4, 2019, 10:25am UTC](https://forums.buildingsmart.org/t/definition-ifc-markdown-and-version-control/1774/7 "2019-09-04T10:25:57Z")

</div>

It’s up to you and bSI, and standards

If you still think STEP and EXPRESS and even “XML” are good enough, continue it.

---

<div class="post-metadata">

**Author:** ![TLiebich](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/tliebich/32/71_2.png) [@TLiebich](https://forums.buildingsmart.org/u/TLiebich)\
**Post date:** [September 4, 2019, 10:31am UTC](https://forums.buildingsmart.org/t/definition-ifc-markdown-and-version-control/1774/8 "2019-09-04T10:31:16Z")

</div>

@ReD_CoDE - please don’t misinterpret - the statement was, that IFC does not have to be rebuilt from scratch in order to utilize UML. Whether eventually UML (or better XMI) becomes the master, from which other data definition standards can be derived (as OGC does it with GML in general (not only with CityGML), i.e. deriving an XSD by a set of conventions from UML/XMI) is a different, but next question. And it will be properly addressed.

---

<div class="post-metadata">

**Author:** ![ReD\_CoDE](https://sea2.discourse-cdn.com/flex016/user_avatar/forums.buildingsmart.org/red_code/32/226_2.png) [@ReD\_CoDE](https://forums.buildingsmart.org/u/ReD_CoDE)\
**Post date:** [September 4, 2019, 10:35am UTC](https://forums.buildingsmart.org/t/definition-ifc-markdown-and-version-control/1774/9 "2019-09-04T10:35:52Z")

</div>

The main issue bSI should solve is this one:

> - Secondly, the logic behind the IfcDoc tool makes the IFC schema and the IFC schema development more dependent on its data modeling tool which today has issues and buildingSMART International has started to develop it again based on UML, but in reality, UML will not solve the dependency barrier, likewise.

> **[GitHub - IfcXtreme/IfcXtreme: The next generation of IfcDoc](https://github.com/IfcXtreme/IfcXtreme)**
>
> The next generation of IfcDoc. Contribute to IfcXtreme/IfcXtreme development by creating an account on GitHub.

And the current approach through UML and XMI I don’t think solves this

I shared the solution to Jon, Leon and Georg
