As custom language injection working with concepts from wiki

[SemanticBeeng]

Would it be possible to make this plugin handle the markdown language extension from Intellij and use the concepts from wiki?

This may sound obscure - hope this image starts clarifying but please advise how I can explain better.

[vsch]

@SemanticBeeng, if I understand the first part, injecting languages into markdown fenced code has been part of the enhanced (licensed) plugin's functionality almost since the beginning. Including code completion for the code fence info (language string).

The full version also has an option for injecting HTML language for HTML block elements so these edit using IDE's HTML support without effort.

As for the second part dealing with "concepts from wiki", can you please explain what you mean by that?

[SemanticBeeng]

My use case is to maintain a wiki with the concepts behind the code (with the plugin) and then to reference them from such embedded / injected text like in my example above : to use snippets of markdown - like in the image - in the code.

Is this making it making sense?

[vsch]

@SemanticBeeng, I can understand that but what I am missing is what do you want the plugin to do with the injected markdown?

Do you want to transform the bare link to an actual document in you wiki?

Do you have flexibility on the syntax for the link? For example, can you just use a reference link: [Monad Transformer]?

If you can then use LinkMap with Reference type, use the Jira Reference for initial content.

The sample allows references matching ITS-(\d{1,5}) to map to links with expansion http://jira.somedomain.com/browse/ITS-$1

This allows an undefined reference of [ITS-0000] to result in a link to http://jira.somedomain.com/browse/ITS-0000

What this does is allows a RegEx to pre-process the reference so it is resolved to a link. This may be of help to you since you can then map all references to the root of your wiki then just the document name in the reference will resolve to the document.

However, validation, completions and navigation do not work for these but I can look into making it work if the replaced link resolves to a project file.

Let me know if this is what you had in mind.

[SemanticBeeng]

Thank you much for the detailed reply, ideas and interest.

Did not fully get the idea of LinkMap: will elaborate on my intent and then come back to it.

The general idea is to have more advanced literate programming tool support integrated in Intellij. Main interest is for Scala but also for Python, R, Haskell, TypeScript, etc.

The business value I see is in keeping application code in sync with concepts from both business domain (Domain Driven Design) but also architecture, design and technology domains (in the example from the image am trying to document design of aecor with concept from functional programming).

In terms of solution am looking to use the combination of markdown with concepts from wiki and code to render documentation artifacts (blogs, books, etc) but also evolve interactively in Intellij.

As inspiration we have

1. specs2 generates user guide from an internal framework that allows combining Scala with text

https://etorreborre.github.io/specs2/guide/SPECS2-2.4.17/org.specs2.guide.UserGuide.html https://github.com/etorreborre/specs2/blob/master/markdown/src/test/scala/org/specs2/text/MarkdownSpec.scala https://github.com/etorreborre/specs2/blob/master/guide/src/test/scala/org/specs2/Website.scala

2. Tut https://underscore.io/blog/posts/2015/12/18/tut.html https://tpolecat.github.io/doobie/docs/12-Custom-Mappings.html - example book written in Tut

Both of them are not interactive in the sense of being able to reference wiki concepts and refactoring all. Tut does use markdown . Specs2 can generate the final result in markdown.

The key requirement is to document concepts and interlink and not just to write blogs or posts. The point is to evolve a conceptualization in wiki that connects multiple resources (project modules, files, blog posts, books, etc) so that people studying that domain can search, understand the concepts and then find them in code.

Of course this is beyond one plugin but you plugin is closest I have ever seen because it maintains the markdown through refactoring and seems it can be used in markdown as injected language (if I understand well).

So, this is not just about putting links in code and translating them. Although that technique might be very useful.

Thoughts?

[vsch]

@SemanticBeeng, the idea of keeping application code in sync with concepts from business domain is a great theoretical goal but impossible to realize in practice because code and business ideas are communicated in completely different languages and deal with different levels of abstraction. There is an irreconcilable impedance mismatch.

It has been a great sell to business heads for decades who have been eager to eliminate the quirky, expensive programmers out of their hair. Unfortunately, most of these business people have no clue to what an implementable specification would look like or how much effort it would take to create. Much of the quirkiness of developers comes from trying to clarify and disambiguate the business domain provided marketing glossy they think is a specification.

The two domains think at different levels of abstraction, as they should. They address different problems and exist in different environments.

It is similarly hard for most programmers/developers to understand or care for business issues. Not their interest. If it was, they would be doing business not software development.

All adding business rules to code will do, IMHO, is add irrelevant noise to code which is already complex and cluttered enough without it.

Another problems is by the time business rules are made clear and precise enough to make sense in a programming environment, you will have created at least pseudo code. Except it is untested nor verified, business people won't understand it and neither will the programmers because it will be "Esperanto" of programming which no one cares to learn.

I have seen many, many attempts at this over the decades and no one came even close to making something worth learning much less making it central to their mission critical projects. In the end it is easier, faster and cheaper to keep the two worlds separate.

I also don't see why the great hype for better documentation when hardly anyone bothers to read it once it is created. What they really want is a quick reference from which they can extract the needed information in minimal time and get on with their work.

I don't put value in comments, much less other documentation because I do not trust it to represent what the code really does. I prefer to read the code since this is what is executed, not the comments or the docs.

For me, even javadocs are a waste of time except in stable, reusable code. If the code is in development or rapidly evolving, comments tend to take more time to maintain and keep in sync than the value they provide. Especially when they get out of sync with the code and are nothing but misdirection.

[austintraver]

@vsch This was a good response, I enjoyed reading it. I think this issue can safely be closed

[SemanticBeeng]

I also don't see why the great hype for better documentation ...

My point as not about "documentation" but about "design". But even about "documentation" this is not correct: best code bases have kickass documentation and we really depend on it. See Akka for example but there are many.

Sure, close this. The response has good points about coding but understated the premise of my ask: literate programming, Domain Driven Design, (ubiquitous language), design process in code, etc.

In the overall SDLC we work with at least three domains:

• business domain (including here requirements also) : what and why
• design domain - how
• technical domain (frameworks. general programming languages, etc) - what pieces to leverage

Unless these three are not weaved together harmoniously across the team and time we get the regular code: cryptic, non-reusable, to be re-written. Anyway, we agreed to disagree.

For others that relate to my points: have since been looking at laika: functional library in Scala

• https://planet42.github.io/Laika/01-about-laika/01-features.html
• https://planet42.github.io/Laika/03-preparing-content/01-directory-structure.html
• https://planet42.github.io/Laika/05-extending-laika/03-implementing-directives.html