Semantic markup: LaTeX, DocBook or ???

He wrote a comment on the article and realized that it was necessary to make a separate post.
As many noted there in the comments article sucks, the person does not understand and mixed everything in a heap, I will try to share my conclusions from the use of different markup.

I will say right away that I was always interested in the topic of a convenient format, but I didn’t have enough time to work closely, there was a case when it was necessary to work - they wrote user documentation and there all the problems of binary formats surfaced - inconvenient to track changes, inconvenient to work together, a lot of copy-paste (which was I wouldn’t be needed if I had the opportunity to do include), inconvenience when translating into other languages, but my attempts to translate everything into LaTeX did not meet with support and everything died down.

Then one day it was time to quit work and indulge in grafomanism. I always kept LaTeX in my head as a well-known and interesting format, but for simple ones, I started using Markdown . he was supported by GitHub / GitLab, then I was not enough of his capabilities, I switched to AsciiDoc , he was also supported, but then his capabilities were not enough and I had to switch to LaTeX.

LaTeX is good at following:
')

1. It is distributed, most of the questions are easily solved - the search results on stackoverflow and almost everything starts working.
2. Attempting to share the content and design is excellent, it is one of the best and universal patterns in IT (they use MVC , many have switched to SPA , I don’t think I need to explain why this is good).
3. LaTeX is quite readable and quite suitable for human typing.
4. LaTeX is great for working with git.

Unfortunately LaTeX is also not perfect, yes - you can get a good pdf, but:

1. There is actually no separation of content and design in LaTeX in order for it to be so hard to do so, but anyway, some design artifacts will leak into your content if you are doing something more complicated than a trivial example.
2. LaTeX is more like a pseudo-semantic markup - it’s understandable to a person, but the converters don’t know what semantics is behind a specific tag (there is no standard). Therefore, the conversion works very poorly, for some time I managed plastex 'th, but it completely broke down as soon as I used a little more features of LaTeX, although it was not perfect before that.
3. Another problem with the lack of a standard is the inconsistency of packages - I had a case when one package for lists had a good solution for one feature, but did not have a solution for another, and the second package, on the contrary, they conflicted as they defined one environment.
4. Although readability is good, there is much to improve - markdowns like Markdown are, of course, better suited for humans.

When the conversion from LaTeX finally broke, I was forced to turn to the great DocBook 's, this is the XML standard for semantic markup of texts for which there are XSLTs ready for conversion to some formats. But he also has problems:

1. Dokbuk is a “secret” technology - very little information (I don’t even speak about information in Russian), it’s very difficult to begin to figure out how to make even a minimal example, and even more to solve some non-standard problems (if you need a couple of useful links ).
2. This is XML. I believe that a person should not see it, much less edit it. Of course, it would be possible through Gui, but I want to have all the possibilities and not be attached to Gui.
3. You can put xml in git, but the default diffs will not be read very well, you can fasten special utilities to view the xml diffs, but you need to do this, you even tried it once, but I don’t remember how well it turned out. I precisely remember that it is configured locally and it is necessary to repeat the setting after cloning.
4. PDF does not look very good by default, you can customize it in theory, but you don’t want to because of point 1
5. Despite the fact that this is a standard and a standard that has been developing for a long time, there are also shortcomings, for example, I encountered that the bibliography does not include a tag for the source url.

The big plus of the dockbook is semantic markup, this is especially important when you need to convert to different formats, we want the readers to be comfortable, which means they need to be given in the format that is convenient for them - pdf of different sizes for different screens and printing, mobi for Amazon readers, someone fb2 (this is just the problem - you need to make your xslt, there is no ready one), a multi-page html version is needed for reading online, etc.

I think everyone understands that the semantic markup does not prohibit the editor to have a “happy life” , so this cannot be an argument against semantic markup. True, I did not thoroughly investigate the issue of gooves, at first glance, under Linux, somehow everything is not very good with geyami for docbook, although there are options.

It turns out that mankind has not invented a normal solution, there is an interesting attempt - DocOnce , but there are not all the possibilities there either - but in theory you need to have all the features of the dockbook, plus DocOnce is some kind of crutches, the authors write that there simply rehexes everything, those. There is no normal parser, which means there will be many bugs.

As a result, I “finalized” (added empty tags) LaTeX markup, in order to convert simple rehexes into a dockbook, and from it to do all formats except PDF because pdf is easier and more beautiful to do out of latex.

Those. for myself, I made a crutch crossing the advantages of LaTeX and DocBook - I have a more human markup than xml (and giving a good pdf), but at the same time it is easily mapped to a docbook to get its advantages in the form of high-quality conversion to many formats.
Of course it is difficult to call it a good decision, but I did not think of a better one.

The correct solution would be to create a human-readable markup like DocOnce, but with a full set of DocBook features (converting this markup into a dockbook from this markup, and from it to other formats), but I already had a desire to pick up a library and describe the syntax in some notation like BNF , but this task did not go with me, maybe someone will have more enthusiasm.

This is at a minimum, and you can go further - there are still many types of information that could be added to the semantic markup standard, for example, plantuml- type things , it’s also good that he could not only draw formulas, but also calculate substituting the result and so on .

Well, apparently you need a beautiful goove editor, since this causes problems for some users.