On 2024-02-01 at 18:36:48, Hans Meiser wrote: > > Could you, please, clarify what kind of git documentation are you > > referring to? Are you having git man pages in mind? > > Yes, these in particular. > > From my point of view, many of these are quite unorganized, hard to > read and – as I believe – need a fix-up. Markdown could replace the > currently used language, so editing them would be more easy, proving > support for preview and lint the documentation. We've discussed moving to Markdown. Unfortunately, while Markdown is great for HTML, it's pretty terrible for things that are not HTML. Certainly there are tools that convert Markdown to other formats, but I'm not aware of any single tool (outside of Pandoc[0]) that does so into all the formats we offer, including HTML, PDF, Texinfo, and manual pages. Markdown also comes in a large variety of variants and writing documentation to please any substantial number of tools is very difficult. AsciiDoc supports converting into all of those things either directly or through DocBook, and it's flexible enough to allow a decent amount of customization, which we take advantage of. It also has relatively little variation. Both of these are part of the reason that Git LFS moved from Markdown to AsciiDoc. > >Quite frankly, I think you've missed some important points from the > > Konstantin's message. To sum it up a bit, not having continuous support > > is simply unacceptable for any kind of a long-term project. > > As I wrote, once installed on-premise, no-one will shut down an > on-premise git server except for yourself. It can run for eternity. > You just need someone to administer it properly and publish the > website. Yes, and that would be someone at kernel.org, which is a nonprofit. Maintaining a busy Git server takes server resources and sufficient staffing to ensure that things work properly and that problems are resolved in a timely manner. It also comes with potential security risks. The mail-based approach will likely remain for the Linux kernel, so someone will have to maintain this in addition. Are you offering to provide long-term funding to kernel.org to provide the necessary resources and staffing? > In the end, it's all just about git. You may create your own git > webserver (https://git-scm.com/book/en/v2/Git-on-the-Server-GitWeb), > or just use an existing one, like the GitLab server: > https://about.gitlab.com/install/ The Git project has tried for a long time to be neutral on any particular external piece of software. Installing a GitLab server as our preferred development platform would promote GitLab as the preferred forge to other users. Similarly, moving to GitHub would prefer GitHub over other forges. That's not a thing we want to do. We also don't accept patches or features for the benefit of one particular forge or external project. Patches and features must be of general benefit to the project at large. [0] Pandoc is built in Haskell using GHC, which has decent architecture support, but quite poor OS support outside of the most common platforms. Relying on it would be a serious regression in terms of documentation support. -- brian m. carlson (he/him or they/them) Toronto, Ontario, CA
Attachment:
signature.asc
Description: PGP signature
