Documentation suggestion: introduce includes to "don't repeat yourself" (DRY)

[eriksjolund]

Parts of the web pages

https://docs.podman.io/en/latest/markdown/podman-run.1.html

https://docs.podman.io/en/latest/markdown/podman-create.1.html

are identical. By introducing some sort of include mechanism, the duplicated documentation sources could be avoided.

(I have a vague memory that I might have suggested this before)

[Luap99]

I think this is a good idea, sometimes we will update only one of the pages and forget the other, the same for options in podman pod create.

I don't think we can do this with the current markdown format files or at least we would need adapt this. I fear that the added complexity with such tooling could be more difficult to manage than the current duplication.

[rhatdan]

The issue is these are used as both markdown and to generate man pages. If markdown had an include directive, perhaps we could do this, or we would need yet another format to store the content in it.

As much as this is a pain to manage, I am not sure that alternatives would be better.

[eriksjolund]

Another approach: Create some script that is automatically run for new GitHub PR:s. The script should
warn or error whenever there is an edit in a text chunk that occurs many times.
The script should not warn if the same edit is made in all of the copies.
Such protected text chunks could for instance be defined as a identical text chunks consisting of 3 lines or more.

[Luap99]

@edsantiago WDYT?

[edsantiago]

This is something I've wished for often, most recently yesterday when dealing with #14914. There is a LOT of horrible duplication in the man pages.

As has been mentioned, it's a really hard problem. There is no include provision in markdown; even if there was, it would not work well with option sorting. @eriksjolund's script suggestion is a good one, but how does this tool identify the common sections? Let's cogitate, though, and keep the suggestions coming.

[eriksjolund]

Mutating text has similarities to mutating DNA which is studied in bioinformatics. In bioinformatics you do sequence alignments. Maybe something like that could be useful to identify the text chunks that match 100% but also text chunks that match somewhat less than 100%. Just brainstorming ...