Unrelated to religious fights: for the end user documentation as shipped in the Javadocs we use Markdown and we already have a converter in the Gradle build that for example builds the overview page with all modules and links to system requirements,... It uses flexmark: https://github.com/apache/lucene/blob/main/gradle/documentation/markdown.gradle
How about just integration of dev docs into the general documentation. It might also be useful to anybody just reading our docs on how to contribute. For the help in Gradle, we can just tell the fkexdown library that's in use to output plain text (see https://github.com/vsch/flexmark-java/issues/63) so "gradlew testHelp" or similar shows it in console friendly way. In GitHub any format is rendered automatically, so I don't care. Uwe Am 16. Oktober 2021 09:57:20 UTC schrieb Michael McCandless <[email protected]>: >LOL religious wars! > >Until we can agree on what markup language (or none at all -- it has a nice >appeal! -- I am old fashioned too!), maybe we could start simply by just >removing the stale docs? We don't need agreement on markup language yet to >do that? Baby steps, progress not perfection. > >Mike McCandless > >http://blog.mikemccandless.com > > >On Sat, Oct 16, 2021 at 5:37 AM Robert Muir <[email protected]> wrote: > >> But that's not the situation, instead we have different files in all the >> different markup languages already. Dawids is just another. >> >> Please kill the asciidoc right now, so that we have one less. >> >> On Fri, Oct 15, 2021, 4:28 PM Dawid Weiss <[email protected]> wrote: >> >>> > We also have the help/ folder which is plaintext since it can be >>> invoked with ./gradlew helpXXX. Someone should decide what goes in help/ vs >>> dev-docs/ >>> >>> In all honesty, I prefer plain text files, much in the spirit of RFC >>> documents. They work well, they display well on all known terminals >>> and they don't require any added knowledge of N different flavors of >>> markup formatting languages. I know some of you may disagree but it's >>> not going to change my mind on the subject - sorry for being >>> old-fashioned. >>> >>> D. >>> >>> --------------------------------------------------------------------- >>> To unsubscribe, e-mail: [email protected] >>> For additional commands, e-mail: [email protected] >>> >>> -- Uwe Schindler Achterdiek 19, 28357 Bremen https://www.thetaphi.de
