Documentation language

I have seen earlier requests for this in the discussions, but I did not find an answer. So I am trying to revive the question. Is anyone working on a documentation language which provides basic markup similar to HTML? If not is anyone interested in helping me develop one?

Here are my (non-exhaustive) requirements:

  • basic markup without language-specific extensions. A small set of markup concepts (i.e. more HTML-like than Docbook-like)
  • strict separation of structure and presentation
  • strict rules so texts will have a uniform structure:
    • hierarchical section levels
    • ancestors and descendants (e.g. strong inside a strong at any depth is not allowed)
    • be able to extend it with documentation elements specific for a language (e.g. links to types or members in Javadoc)
    • have multiple root concepts:
      • complete document
      • single section at a specific level (e.g. an h3 with its associated content)
      • content of a section at a specific level. The content can only contain headings for lower levels (e.g. used for body text of Javadoc assuming that the heading itself for that level is generated by the Javadoc tool)
      • inline items only (used for text of param and return tags in Javadoc)
    • reasonably user-friendly editors. I understand a WYSIWYG or even a WYSIWYM editor can probably not be built, but it shouldn't be too cumbersome to read/edit text

    I already have a tiny prototype of a documentation language, but unfortunately I can't get it working as I want to (largely due to lack of experience with MPS). So before putting a lot more effort into it I would like to know if it is possible to build a documentation using MPS as it is now. And if it is possible, I would like to know if it is smart to do it by creating a language, or that it would be much better to simply add a HTML editor component to an editor and let that do all the heavy lifting.


    Johan Stuyts

    Hi Johan, I beleive that the documentation language  would be an interesting project.
    I can try to help, where are  you hosting it?

    I am not hosting it yet. It's in an experimental phase now (only about a dozen concepts). I thought it might be a good starter project for me to get to know MPS because I didn't have to deal with all the MPS concepts (type system, data flow, etc.) at once.

    The biggest problem I am facing now is that I can't get a nice flow of the text when I add style (strong, emphasis, code, citation, etc.). I already changed my model so each word is represented by a single concept instance, but this seems overkill to me. It enabled me to improve the flow a bit, but it still becomes cumbersome to follow the text depending on the number of words inside a style concept.

    Other issues I am having is consuming key events so I can handle spaces, backspaces, etc. in a way that will make text editing feel more natural.

    I guess somebody at JetBrains must have attempted to build a documentation language as it has come up a couple of times in the past years. I understand MPS was not designed for markup languages, so I love to hear advice about whether the possibilities and restrictions of MPS allow for a powerful documentation editor. If the end result would be clumsy due to the restrictions, then too few people will use (and contribute to) it.

    I don't know if you know the XMLmind XML Editor and its standard support for XHTML, but I am aiming for something similar. The XMLmind XML Editor has some shortcuts for common constructs enabling basic WYSIWYM, but in general when you edit the document you are well aware of the concepts of the document (i.e. the HTML tags). In that respect it is similar to MPS.

    I created a project with a wiki so everybody's requirements and opinions can be documented in a central place: (Registration and a project join request are required for editing the wiki).




    There had been some 'textLanguage' or 'bookLanguage' around for some time but I couldn't find any traces of it in MPS project now.
    Probably it wasn't too successful anyway.
    This field is not explored and I can't suggest the best way to build the documentation language right away. There are many ways to achieve things in MPS and, most likely, several prototype languages will be required to understand, which approach is working best.

    Aren't you going to publish you current experiments as well?



    Sounds like an interesting project - unfortunately I've currently no spare time to help you :-(

    But there is a question that comes in my mind: how do we do a team work on a project with MPS? I mean, with java projects there are java files and VCS' do an excellent job in tracking and merging the files. As I understand, MPS stores the sources in a repository rather than in normal text files. Has somebody experience in versioning and concurrently modifying MPS source code?

    Best regards



    Too bad JetBrains doesn't have a documentation language.

    Anyway, I've put my experiments in a Subversion repository as you requested:

    I have also created an issue tracker to better keep track of the problems encountered during the development of a documentation language:

    In addition I added you to the public group so you are able to edit the wiki.



    Thank you. I have  already tried to start discussion using comments to the wiki main page, but with  no success. Probably because comments are hard to notice.

    Comments of the wiki won't work unfortunately, because I do not receive a notification when someone adds them.

    I have added answers to your comments to the wiki:

    Feedback from everyone is welcome.



    Permanently deleted user

    We don't store our code in repository. We use xml files. As a consequence, you can use any VCS you like: Subversion, CVS, Perforce. All the VCSes that are supported by IDEA are supported by MPS, thanks to the IDEA plaftofmr.

    Since MPS' xml files aren't very readable and merging them manually isn't easy task, we have special merge tools. If you update your project from MPS, MPS merger is invoked and you can merge changes.

    I've been  experimenting with documentation language for some time.
    I'm attaching the  results of experiments here because I haven't find a way to do that at  zybber.
    The project includes  my documentation lang prototype and small 'How to' documentation written in that  language :) (see sandbox).
    Take a look, let me  know if you have any questions.
    Probably, I have to  create a  short description at zybber to explain how certain functionality is achieved or  why some MPS feature is used.
    There are also some  MPS issues has been revealed which I hope will be fixed in future EAP  builds.
    Regards Igor.


    Hi Igor,

    (Sorry for my late reply)

    Your language is similar to mine. I see you have the same problems I have: layout. It would be really great if there was some kind of text-flow layout. This would prevent having to manually wrap text and allow styled text spanning multiple lines to flow naturally.

    Is it possible to write custom layouts now?




    Nop, I don't have layout problems that you have:)
    My 'inline items' flow smoothly from one line to another except that the separator cells (which I use instead of paddings) shouldn't flow that way. Unfortunately, they do and this behavior leads to unwanted indents and blank lines. After the problem has been fixed the text flow became near perfect.

    I've also looked into your project and found why flow layout doesn't work well for you.
    To fix it, in the editors of Emphasis, Strong and Code concepts do the following:
    1. set property 'cell layout = Flow' in root cell collections
    2. remove style 'layout constraint = punctuation' form root cell collections
    3. remove style 'layout constraint = punctuation' form child list cells

    Then the text flow will be much nicer (see pics attached) and I hope you won't be needing a custom layout anymore (It's not possible anyway).

    In my version of documentation language I attempted to use sequence-of-words concept (vs single-word concept in your language) - issue [#18] Combine multiple words into a single concept

    That's the major difference between our two languages.
    It's up to you to decide which approach is more promising.
    Sequence-of-words approach eliminates much of hassles with event handling but word wrapping becomes semi-automatic (at some point you should press <Enter> to start next sequence which can be layouted to the next line).

    On the other hand, we could analyze problems with event handling and make improvements in MPS which will remove that obstacle.

    In my language I've also used variety of MPS features and tricks which are good to learn in any case. I'm going to find some time to document them in the project wiki at Zybber.

    Regards, Igor


    BTW, it seems impossible to comment or edit issues in Zybber's tracker:(

    [#20] Cannot consume key events

    ...There is currently a workaround for the concept 'Word' which removes leading
    and trailing whitespace of the attribute 'value'...

    This can be done using 'transactional property' cell. Unfortunately, only in next MPS build - in current build it doesn't work properly.

    [#21] Add breadcrumbs to indicate nesting of concepts

    Breadcrumbs should be added so a user can clearly see which concept is active
    and what its ancestors are.

    Try to use Alt+F2 - open selected node in project tree. May be that's all what you need?



    Great, this helps a lot. I still don't get the exact image you have (some parts are not rendered), but it flows much better.

    I prefer to use a sequence of words as a single concept because using a concept instance for each word seems overkill. However I do want automatic wrapping so I might stick with single words.

    I noticed you did things differently in your project. I will take a look at them.




    Strange that you cannot comment on the issues. I just increased your privileges, so maybe it will work now. I actually want everybody to be able to comment without having to be assigned to the project and without having to grant them privileges (registration would still be required), but unfortunately this seems impossible.

    #20: okay, I will wait for the next build.

    #21: actually I would like to see the breadcrumb within the current concept that I am editing. Alt+F2 works well but it changes the focus, making it is a bit cumbersome to use. I enabled 'follow from source' in the tree, but this did not work for me.



    To get the picture  as it is on the screenshot I've also killed 'background color' properties in some  cells. For some reason they were masking text in constant cells.

    Please sign in to leave a comment.