Updated IFC 4.3 documentation website and process

MoultMoult
edited February 2022 in General

For something as ambitious like IFC to be the "HTML / CSS / JS" that describes our building industry, the documentation leaves a lot to be desired :) In fact, in the past it was maintained using a tool called IfcDoc which only worked on Windows. Today I'd like to share some of the amazing developments that have been happening with IFC4.3.

For IFC4.3, buildingSMART is revising their processes so that the IFC specification is described using UML instead of EXPRESS, so in theory you can use any free software to edit UML and modify the IFC shema. All docs are now also in Markdown and tracked with Git, which makes it a much more inclusive experience. Similarly, there is now a public process to allow everyone to get involved with suggesting improvements to the specification.

First, before we see what's new, here's a flash from the past of how things used to be:

Here's the new IFC docs (live generated, changing every day until the ISO submission on March 6): http://ifc43-docs.standards.buildingsmart.org/

Some of the improvements you'd enjoy:

  • Allows the IFC documentation to be generated without the need for proprietary software, and work cross platform on Windows, Mac, and Linux.
  • The written documentation is now fully captured in plain text using Markdown, making it easy for anyone to edit the documentation without special training.
  • A built-in search feature. How did we live without it :)
  • All written documentation changes are tracked using Git, allowing anyone to edit and see edit histories.
  • Using Github, anybody can make quick online "Wiki" style edits without bespoke software installation.
  • Documentation layout is easily customised using HTML templates and CSS styles
  • Schema changelogs are auto generated instead of relying on manual logs
  • Schema diagrams such as entity inheritance trees and concept diagrams are automatically generated with automatic layouting, with SVG support and clickable links to ensure they are searchable and always current
  • Users can generate their own interactive diagrams that can be maintained and checked without the need for image editing software
  • Beautifully rendered LaTeX math equations
  • All schema entity references are automatically linked and referenced
  • All figures are automatically captioned and numbered
  • All headers and figures are anchored for sharing portions of the specification with anchor links
  • Using markdown and standardised templates helps ensure consistency in layout, typography, tables, links, notes, and references.
  • Built-in quality checking procedures during documentation generation.
  • Hovering over entities shows a quick popup preview of common attributes and data types for convenience
  • Shows inherited concept usages on all entities
  • Quick section jumping to browse long or complex pages
  • Navigation breadcrumb easily communicates the domain scope of the current entity you are browsing
  • Automatic syntax highlighting and line numbering for EXPRESS, STEP, XML, and JSON code snippets and examples
  • Examples are shown with thumbnails and automatically referenced by entities
  • API for quick documentation lookup
  • Mobile friendly (well, we plan on it, I would hope)

The docs are published under CC BY-NC-ND 4.0. I've asked what the code is under (Update: it will be MIT licensed!). You can see an explanation of how the code fits together here: https://github.com/buildingSMART/IFC4.3.x-development/blob/master/code/README.md

You can see a list of issues (very fast paced right now considering an upcoming hard ISO deadline on March 06 unfortunately) here https://github.com/buildingSMART/IFC4.3.x-development/issues (yes, I've been methodically combing the forums and various channels for every single comment the public has given over the years) as well as a rough draft of how to allow public changes and engagement and ensuring that domain experts still review / QA for ISO requirements here https://github.com/buildingSMART/IFC4.3.x-development/wiki/IFC-4.3.x-Change-Process

Tagged:
CoenbitacovirchunchkCyrilbrunopostleDarth_BlenderAceCadGiruduncanNigeland 4 others.

Comments

  • duncanduncan

    I'm announcing this for a week or two to make sure people see this. It's important that we tell people about the great improvements there are from bS & IFC.

  • MoultMoult
    edited February 2022

    Here's a bullet list of the improvements made from a free software / openness / vendor neutrality / transparency perspective I've noticed with buildingSMART over the past couple of years:

    • Public forums using free software Discourse. A small step that led to everything else. There was a time when there was no public communication platform.
    • Deprecate IfcDoc which relied on Windows. Now cross-platform and I can run it on Linux.
    • Transparency in version control using free software Git
    • Transparency in text-based issue tracking and public engagement as opposed to closed door decision making
    • Potential relicensing under MIT license for the server
    • bSDD developed under MIT license.
    • IFC test data sets licensed under CC-BY 4.0.
    • IFCJSON MIT licensed.
    • Most recently: doc generation code to be MIT licensed.

    Note all specifications (IFC, BCF, IDS) are historically licensed under CC-BY-NC-ND 4.0 - the NC-ND is non-free, but a step forward compared to a time when it was fully copyrighted in IFC2X3. Other specifications. For comparison, HTML is CC-BY, CSS is similar to CC-BY, Javascript is similar to CC-BY-ND. There is some discussion in the Github issue about how this difference might be resolved.

    Nigeljchkochiosvarmskrandeakseltcarlopav
  • akseltakselt

    This is great!
    I just wanted to browse http://ifc43-docs.standards.buildingsmart.org/ - But to my surprise - it currently seems to be offline? Has the url been updated?

  • MoultMoult

    @akselt the link seems to be working for me? Perhaps you can check with https://isup.me ?

  • akseltakselt

    @Moult said:
    @akselt the link seems to be working for me? Perhaps you can check with https://isup.me ?

    @Moult It is working here now also. Suspect the server just had a few hours/minutes of downtime...

    Moult
  • posaposa

    Hi,
    Is there more information on usege of "API for quick documentation lookup" ?
    I have found out that if we use for example :
    http://ifc43-docs.standards.buildingsmart.org/api/v0/resource/IfcSpace
    Result is in JSON, which is perfect.

    However what is an API call in order to get similar information for example "Pset_CurtainWallCommon" ? Example:
    http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/Pset_CurtainWallCommon.htm

  • duncanduncan

    @aothms or @Moult this sounds like someone one of you could easily answer?

  • aothmsaothms

    @posa, yeah that API is hardly anything. It does seem to do something, but doesn't list anything interesting for the properties http://ifc43-docs.standards.buildingsmart.org/api/v0/resource/Pset_CurtainWallCommon

    It's not a lost cause. Someone just has to compare the api route [0] with the html route [1] and spot the differences. Are you interested in contributing?

    Otherwise for practical purposes I would probably recommend the full JSON dump we generate https://github.com/buildingSMART/IFC4.3.x-output/blob/master/IFC.json?raw=true

    [0] https://github.com/buildingSMART/IFC4.3.x-development/blob/master/code/server.py#L826-L835
    [1] https://github.com/buildingSMART/IFC4.3.x-development/blob/master/code/server.py#L959

  • GorgiousGorgious

    There are a now several functions in ifcopenshell-python to parse the docs : ifcopensell.util.doc. Link to the relevant module

    It does not yield the attribute types, though.

    Example :

    import ifcopenshell.util.doc

print(ifcopenshell.util.doc.get_property_set_doc("IFC4", "Pset_CurtainWallCommon"))

    Result :

    {'description': 'Properties common to the definition of all occurrences of IfcCurtainWall.', 'properties': {'AcousticRating': {'description': 'Acoustic rating for this object. It is provided according to the national building code. It indicates the sound transmission resistance of this object by an index ratio (instead of providing full sound absorbtion values).'}, 'Combustible': {'description': 'Indication whether the object is made from combustible material (TRUE) or not (FALSE).'}, 'FireRating': {'description': 'Fire rating given according to the national fire safety classification.'}, 'IsExternal': {'description': 'Indication whether the element is designed for use in the exterior (TRUE) or not (FALSE). If (TRUE) it is an external element and faces the outside of the building.'}, 'Reference': {'description': 'Reference ID for this specified type in this project (e.g. type \'A-1\'), Also referred to as "construction type". It should be provided as an alternative to the name of the "object type", if the software does not support object types.'}, 'Status': {'description': 'Status of the element, predominately used in renovation or retrofitting projects. The status can be assigned to as "New" - element designed as new addition, "Existing" - element exists and remains, "Demolish" - element existed but is to be demolished, "Temporary" - element will exists only temporary (like a temporary support structure).'}, 'SurfaceSpreadOfFlame': {'description': 'Indication on how the flames spread around the surface, It is given according to the national building code that governs the fire behaviour for materials.'}, 'ThermalTransmittance': {'description': 'Thermal transmittance coefficient (U-Value) of a material. Here the total thermal transmittance coefficient through the wall (including all materials).'}}, 'spec_url': 'https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/schema/ifcsharedbldgelements/pset/pset_curtainwallcommon.htm'}

    aothmsCoenvpajicArv
Sign In or Register to comment.