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
>>> 
> 

Reply via email to