Definition IFC - Markdown and Version Control

Developers IfcDoc Tool
1

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:

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

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

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

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

1 Like
2

Beautiful work, @jonm !

3

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

would become

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

190904%20circle%20with%20images
190904 circle with images.png1285×981 57.4 KB

instead of

190904%20circle%20markdown%20without%20images
190904 circle markdown without images.png1193×981 56.7 KB

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.

1 Like
4

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.

5

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

6

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.

7

It’s up to you and bSI, and standards

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

8

@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.

9

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.

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

I shared the solution to Jon, Leon and Georg