Texopic and slow-paced problem solving

I updated Texopic spec today. Though I have growing dissatisfaction to this format.

Texopic has at least four potential flaws that can make life miserable for future programmers.

In the other hand it shows how certain problems require their time.

Macro escaping syntax

Macro character '#' must be preceded by blanks or '{' '}'. Otherwise it must be preceded with ';'. The macro eats the immediate ';' before and after it.

I picked this kind of curious syntax for escaping macros, because it makes it unlikely to mangle the URLs that have hash character present in them.

Preformatted blocks

The preformatted block is formed by indentation, preceded by ## -macro. This is going to be very difficult to syntax-color and does not preserve the exact spacing of the text.

Environment-dependent structure

Texopic defines a structure, but the parser needs to be aware about the macros that form segments or separate elements in the blocks.

Space-canonicalized URLs

If URLs have consecutive spaces then they are mangled by texopic processor to contain only single space. This can be avoided by percent encoding the URL and replace the spaces with %20.

Difficult to implement correctly

I have written a generator and a parser for the Texopic syntax. The implementation was difficult. If you get it wrong it parses some fringe cases wrong and it requires lot of care to get the correct results.

Segment ending dilemma

Text is presented in segments, and segments end to blank lines, but there are some types of segments that you might expect to end earlier. For example #title.

#title Title goes here
Paragraph starts here.

The above is incorrect in Texopic and results in one long title instead of what the author meant to do. Other systems have solved this by wrapping the whole title into a macro. Example below shows how Racket's scribble handles it:

@title{Title goes here}
Paragraph starts here.

The similar things are expected to happen with image and video macros.

Uses for segments

A segment is an odd concept. It is a tag to an element that resembles paragraph. With groups it is a vertical element. But that's about the only reason it has for being there.

Segment is a 'vertical macro' that cannot contain other segments. A group is a 'vertical macro' that can contain other segments and groups and can have 'separators' to section itself.

Updates

The major update I made to the syntax recently is related to the paragraph behavior. I disallowed the macros spanning across paragraph breaks or preformatted blocks.

The update makes the language more regular because we avoid some surprising cases where the horizontal macros would contain vertical elements.

Decision

The gut feelings around Texopic prevented me from providing a documentation system for Lever a month ago. I have retained the feeling although I was supposed to fix it.

I have to make the decision of whether I use Texopic for my documentation. I feel the answer should be 'Yes'.

Slow-paced problem solving

Texopic shows out how certain problems may take very long time to get solved. The problem solving process is long.

Things and ideas may require adjustments over weeks or even years after they have been created.

Similar posts