On Thu, Sep 28, 2023, at 18:26, Matt Sicker wrote: > AsciiDoc offers syntax for most of the things that Markdown requires > you to use raw HTML for. Also, the default output format for AsciiDoc > looks a lot nicer than Markdown, but that’s always customizable.
The output highly depends on the processor. AsciiDoc is feature-rich, but also not as widely adopted as Markdown. It is also more complex, due to the high number of features. I am using Markdown for everything that is lightweight, such as blogs, READMEs, or notes because of it's simplicity. I am using AsciiDoc for technical documentation, books, and anything else that requires complex structuring. (this is not rhetorical, I am actually writing my current book in AsciiDoc) I don't think Markdown should be dismissed so easily. I would underestimate how quick people are to help contribute with Markdown formats compared to AsciiDoc. For the landing page, I don't think we actually require AsciiDoc, but if this is the only blocker, we use the Jekyll plugin for AsciiDoc (provided by the AsciiDoc team) Kind regards, Christian > >> On Sep 28, 2023, at 10:35 AM, Ralph Goers <ralph.go...@dslextreme.com> wrote: >> >> I don’t mind AsciiDoc but I have had a few things I couldn’t format with >> AsciiDoc. I am not really sure why AsciiDoc is preferred over Markdown. The >> only problem I have had with Markdown is that some tools don’t support some >> of the latest features. >> >> Ralph >> >>> On Sep 26, 2023, at 2:23 PM, Matt Sicker <m...@musigma.org> wrote: >>> >>> Infra supports publishing any sort of site output as long as it’s published >>> via committing to either subversion or git. For git, this is via the normal >>> asf-site and asf-staging branches similar to ghpages branches on GitHub. >>> Since we can set up GitHub Actions to commit to those branches, we can >>> support any static site generator that can be invoked from an Action. >>> >>> Given Volkan’s argument around JBake, I agree that it would be the easiest >>> thing to use. Site generators based on Python or Ruby tend to ossify around >>> a bunch of random dependencies thanks to the clusterfuck that is Python and >>> Ruby package management which is somehow only slightly less bad than the C >>> and C++ ecosystem. >>> >>> Also agreed on AsciiDoc; Volkan’s reasoning here is exactly why I migrated >>> various documentation to AsciiDoc here in the past. When we first used >>> XDoc, this was an annoying mix of XML and XHTML where our files typically >>> didn’t even validate under the referenced XSDs. I had initially migrated >>> those files to Markdown, but I had to use HTML occasionally. AsciiDoc was >>> the first markup format that didn’t require these escape valves, and they >>> theoretically support template variables, too, so there’s no need to run >>> them through a preprocessor. >>> — >>> Matt Sicker >>> >>>> On Sep 25, 2023, at 04:20, Volkan Yazıcı <vol...@yazi.ci> wrote: >>>> >>>> Great initiative to revamp the Logging Services landing page! Go for it! >>>> But don't change JBake and stick to AsciiDoc, please. >>>> >>>> *Summary:* >>>> >>>> 1. JBake is great, reproducible, and familiar >>>> 2. "INFRA support" is not a valid argument >>>> 3. Markdown is a dead end >>>> 4. The future should ideally not be individual websites >>>> >>>> *JBake is feature-wise on par with alternatives* >>>> >>>> There are a plethora of static site generators; Jekyll, Pelican, Hugo, >>>> JBake, etc. Almost every language ecosystem has its own take on it. But >>>> they all boil down to a couple of basic conveniences: >>>> >>>> - pick a typesetting format of your preference (AsciiDoc, Markdown, etc.) >>>> - generate pages with a templating engine of your preference (Velocity, >>>> FreeMarker, Handlebars, etc.) >>>> - compile it to a bunch of static HTML files >>>> >>>> Some even include batteries: >>>> >>>> - built-in plugins (sitemap, tagging/labeling, search, etc.) >>>> - preview (so you don't even need an HTTP server of yours) >>>> - hot reload (so you don't need to compile it manually every time) >>>> >>>> JBake excels in all these areas. >>>> >>>>> docker run --rm -p 4000:4000 --mount type=bind,src=$PWD,dst=/root/build >>>> --mount type=volume,dst=/root/build/node_modules -it >>>> apache/privacy_apache_org serve --watch --incremental >>>> >>>> Uh... That hurts. This is how you can achieve the same in JBake: `./mvnw >>>> jbake:watch`. >>>> >>>> *The unspoken killer feature: reproducibility* >>>> >>>> I have been tinkering with static site generators for more than a decade – >>>> I love them. I don't know of your experience, but anything beyond Java >>>> sucks a big time when it comes to reproducibility. You cannot run a Ruby >>>> application written 10 years ago on a modern operating system. Many Ruby >>>> libraries depend on system libraries that either are not shipped with the >>>> distro anymore or broke the ABI in the past. I need to use this >>>> hand-crafted `Dockerfile` >>>> <https://github.com/vy/vy.github.io/blob/source/Dockerfile> running on >>>> Ubuntu `14.04` with a particular constellation of Ruby dependencies so that >>>> I can install a version of `nanoc` that compiles my website. It is an >>>> operational nightmare. >>>> >>>> But let's talk about Java and JBake: `./mvnw jbake:watch`. This only >>>> requires the host to have a decent OS, shell, and JDK. That is all. No >>>> more, no less. Docker? Nah. Python? Nah. Some weird OS package? Nah. I can >>>> confidently say this command will highly likely run without a single line >>>> of change for several decades. Given its historical track record, I don't >>>> think any other alternative can beat Java in this area and it is of >>>> uttermost importance given how hard it is for the PMC to afford time on the >>>> website. >>>> >>>> *The argument of familiarity* >>>> >>>> 90% of Logging Services committers are Java developers. That is where our >>>> expertise lies in. If you throw at them a `pom.xml` and a bunch of AsciiDoc >>>> files in `src/site/asciidoc`, without blinking an eye, they would correctly >>>> guess what to do. Moving away from this safe zone to uncharted territories, >>>> in particular, without factually justifying the rationale, will simply do >>>> more harm than benefit, if there is any at all. >>>> >>>> *The argument of "INFRA supports Jekyll and Pelican"* >>>> >>>> What does that support exactly entail? You don't need to compile the site >>>> and push changes to a particular branch that INFRA monitors to serve the >>>> actual domain? It is a dozen lines of GitHub Actions workflow YAML. I >>>> volunteer to do this. >>>> >>>> ASF INFRA serves projects by providing infrastructural functions that >>>> didn't exist... decades ago? Many of its offerings are superseded by far >>>> better alternatives in platforms like GitHub, GitLab, etc. >>>> >>>> *Markdown-vs-AsciiDoc* >>>> >>>> If you look close (and long?) enough to a Markdown-based document >>>> collection, you will notice HTML tags, everywhere. Wait a second? Why did >>>> we decide to use Markdown in the first place? To avoid manually typing >>>> HTML! Yup. The moment you want to do formatting that is slightly >>>> sophisticated (putting a code block under a bullet, annotating source code, >>>> admonitions, etc.) Markdown collapses. Hence, people reach out to sprinkle >>>> HTML into their Markdown. This makes templating impossible in the long run, >>>> since every single hand-written HTML will have its own style, formatting, >>>> structure, etc. which totally defeats the purpose of using a unified markup >>>> language. Hence, please use a markup language that would suffice the >>>> formatting needs of a technical document. Given its rich feature set, >>>> wealthy ecosystem, and large community, I doubt if there is an alternative >>>> here besides AsciiDoc. >>>> >>>> *The future of Logging Services websites* >>>> >>>> In its current state, we have several projects erecting their own websites >>>> by tooling of their preferences: Log4cxx uses Doxygen, Log4j Scala API uses >>>> `asciidoc-maven-plugin`, Log4j 2 and Log4j Kotlin API uses >>>> `maven-site-plugin`, etc. Such a diverse ecosystem requires significant >>>> maintenance investment. Maintenance of not just the tooling, but also >>>> styling. In my opinion, ideally, projects should simply provide a set of >>>> global pages (about, support, etc.) in their `main` branch and >>>> version-specific programmer-friendly-formatted (in AsciiDoc!) manuals >>>> stored in branches next to the code they document, e.g., `2.x`, `3.x`, etc. >>>> That should be the territory where committers deal with their websites. >>>> Enabled GitHub Issues for the project? Edit `support.adoc` in the `main` >>>> branch. Is there a typo in the "Getting Started" page? Edit >>>> `getting-started.adoc` in `2.x` branch, and so on. The rest – converting >>>> these into HTML pages, pushing this to a website, generating release notes, >>>> adding a search bar, styling the page, syntax highlighting source code, >>>> etc. – should be done by a separate "tool" located elsewhere. This will >>>> enable the committers to stop worrying about the website and its >>>> intricacies once and for all. As a bonus, Logging Services will have a one >>>> uniform beautifully-dressed look to the outside world where they can >>>> navigate with ease. The good news is, the tooling is there and it is called >>>> Antora <https://antora.org/>. Somebody just needs to spearhead this effort >>>> and put a handful of strongly-opinionated guys on the same page. 😅 >>>> >>>> *Saving the day* >>>> >>>> Do you just want to save the day? Go ahead, JBake and AsciiDoc are a great >>>> combo. People will appreciate it. It will certainly be an improvement. Do >>>> you want to build the future? You should look beyond a single project and >>>> its individual website. >>>> >>>> >>>> On Fri, Sep 22, 2023 at 8:48 PM Christian Grobmeier <grobme...@apache.org> >>>> wrote: >>>> >>>>> Hello, >>>>> >>>>> the current landing page: >>>>> https://logging.apache.org/ >>>>> >>>>> is done with JBake. We have rather complicated instructions on how to >>>>> re-generate the landing page: >>>>> >>>>> https://cwiki.apache.org/confluence/display/LOGGING/Managing+the+Logging+Services+Web+Sites >>>>> >>>>> The Infra team recommends Pelican or Jekyll to create these kinds of >>>>> pages. I have in-depth knowledge of Jekyll and would like to propose >>>>> migrating the current landing page to Jekyll. >>>>> >>>>> The benefits: >>>>> >>>>> - autodeploy of our changes >>>>> - great support of blogging (I'd like to create one) >>>>> - easy handling and supported by Infra >>>>> - writing content in Markdown >>>>> >>>>> I am aware that we have a discussion open on how to do documentation in >>>>> the future. I would still like to migrate the page asap and - if deemed >>>>> necessary - touch it again later. >>>>> >>>>> So far, I will leave all design/content intact until migrated, and come >>>>> back with additional changes (as the blog) after migration to be discussed >>>>> separately. >>>>> >>>>> If there are no objections, I will start with this move sometime next >>>>> week. >>>>> >>>>> Thanks! >>>>> Christian >>>>> >>>>> -- >>>>> The Apache Software Foundation >>>>> V.P., Data Privacy >>>>> >>> >>
