Use Asccidoc instead of HTML

[vogella]

I suggest we start using a wiki for the N&N. This would make maintaining the pages much easier. Tycho does it to. This would also remove the step in which we copy the content into the help, we should just link to it in the help. AFAIK help does not support external link clicking but we users could copy the link and paste into their browser.

WDYT? @laeubi @akurtakov @Bananeweizen @mickaelistria @BeckerWdf

[akurtakov]

For reference this is when I tried to switch to external link https://bugs.eclipse.org/bugs/show_bug.cgi?id=567027 . IMHO not having N&N in zips is better as it can be corrected post release without respinning.

[mickaelistria]

I've mentioned already multiple times my deep hate for wiki because of its unstructured nature and lack of proper integration into serious maintenance workflows (reviews, contribution tracking...).
So -1 for a wiki from my end; a good master/main branch does the job perfectly.

I don't mind if content is markdown or HTML though.

[vogella]

So -1 for a wiki from my end; a good master/main branch does the job perfectly.
I don't mind if content is markdown or HTML though.

That seems like the best of all worlds. Use markdown in a Git repo which would allow us to still use PR and the like and still only add link it in the repo.

Anyone dislikes this? If not I would bring this to the PMC next week.

[laeubi]

Tycho does it to.

Tycho use a RELEASE_NOTES.MD file not a wiki.

[laeubi]

I don't mind if content is markdown or HTML though.

I recently did a open the web console (F12 in most browser) select the markdown rendered and copy the inner html ... only problem is that github uses html5 and eclipse XHTML so it was not a 1:1 copy then ... See also:

• Migrate to HTML5? #43

[Bananeweizen]

To me some questions are a bit unclear:

• Would the output be frames for the existing php pages on eclipse.org/eclipse/news, or do we expect to generate the complete static HTML, to replace the existing php pages? (Or is that question irrelevant maybe?)
• If we are talking about markdown, do we mean something like Asciidoc (being processed easily via Maven and independent of Github infrastructure) as in the UI Guidelines repository, or are we talking about something that requires Github infrastructure and actions for the conversion, because it's basically Github markdown syntax?

I could help with the Asciidoc part to have a similar workflow like in the UI Guidelines repository and to provide some templating mechanism, but I'm not an expert on other conversion tools.

[vogella]

To me some questions are a bit unclear:

• Would the output be frames for the existing php pages on eclipse.org/eclipse/news, or do we expect to generate the complete static HTML, to replace the existing php pages? (Or is that question irrelevant maybe?)
• If we are talking about markdown, do we mean something like Asciidoc (being processed easily via Maven and independent of Github infrastructure) as in the UI Guidelines repository, or are we talking about something that requires Github infrastructure and actions for the conversion, because it's basically Github markdown syntax?

I could help with the Asciidoc part to have a similar workflow like in the UI Guidelines repository and to provide some templating mechanism, but I'm not an expert on other conversion tools.

My target would be to mark the whole process simpler. So using markdown or Asciidoc directly without any additional processing would be fine to me. The help could just link to the website, "See https://blablabla" for the latest update.
eclipse.org/eclipse/news could also link to it. If we can convert Asciidoc to HTML with little effort that would also be great and we could like to that.

Minimal effort and easy contribution would be target. The easier the better. Writing HTML directly and coping files around for every release feels way to much effort.

[vogella]

Update: PMC is OK with this change. @jarthana will check with his colleagues if the current process adds value to them or IBM until end of next week.

If not we could move the N&N to a Markdown / Asciidoc file in Github and link from the help to it. My preference would be to use the same format as the UX Guideline guide (Asciidoc).

[jarthana]

Looks like we still have questions around how we really want to do this. I am not an expert in this area nor have I been doing this or intend to spend time in figuring out a new method of doing. So, whoever is proposing, please come up with a new concrete way that is better, we can adopt that. I have asked the people who have been maintaining the N&N so far for their opinions as well.

Just one question: Does this mean the N&N content won't physically reside inside Eclipse and the users will have to have an active internet connection to be able to view them?

[vogella]

The plan is:

1.) Have an Asccidoc document containing the N&N for the releases
2.) Have a link in the help to this document

Optional we could setup a GH action to convert Asciidoc to HTML as we do fhe UX guideline.

Does this mean the N&N content won't physically reside inside Eclipse and the users will have to have an active internet connection to be able to view them?

That is the plan, the PMC discussed that a while ago and I think the concens was that an Internet connection is normal these days and that the web experience is better than the native help experience.

[laeubi]

Optional we could setup a GH action to convert Asciidoc to HTML as we do fhe UX guideline.

I just wanted to note that this is actually not a GH action but a plain maven build (called inside an action), if one think it is useful this is something the aggregator build can offer to aggregate all N&N documents into one big HTML file, I just need to know where it should be located and then can setup something like this.

[HannesWell]

Using some kind of markdown, Asciidoc is completely fine, was something I wanted to suggest as well. Indeed, writing N&Ns is more cumbersome than it has to be.

As already mentioned Asciidoc offers a maven plugin (https://docs.asciidoctor.org/maven-tools/latest/), I assume it should not be too hard to get the generated html from that and use it like the now manually crafted html files are used. This would simplify the creation and editing of N&Ns but would keep all use-cases intact.

[jarthana]

That is the plan, the PMC discussed that a while ago and I think the concens was that an Internet connection is normal these days and that the web experience is better than the native help experience.

We happened to discuss this just last week about some ODC setups having to work in a restricted environment. Might be a minority and likely to be struck down as such but just thought I will mention for the sake of it.

[mickaelistria]

If we go for Asciidoc, then I would just recommend dropping all form of publication (eg asciidoc) and just point to the GitHub repo which renders asciidoc well and is usually a good server for such content.

[laeubi]

and just point to the GitHub repo which renders asciidoc well and is usually a good server for such content

I think it depends, if you compare:

https://github.com/eclipse-platform/ui-best-practices/blob/main/index.adoc

with the ascidoc generated HTML here:

https://eclipse-platform.github.io/ui-best-practices/

then yes, github can render something but I won't call this "renders asciidoc well" ... in such case I would simply stick to Markdown as it is what people are much more familiar with.

[Bananeweizen]

... and just point to the GitHub repo which renders asciidoc well and is usually a good server for such content.

If you are only after some markup formatting, then yes. If you actually use multiple documents and you use links between them, nothing of that will work in the github preview. IMO the Tycho release notes are okayish, but something like this guideline needs way more than github provides.

[mickaelistria]

something like this guideline needs way more than github provides.

such as?

[Bananeweizen]

• The processed AsciiDoc is a single HTML file, therefore you can use browser search locally. Github search on the folder on the other hand might be possible, but surely way less intuitive for users.
• Hyperlinks to the generated document are more simple and long-term stable. Moving document parts between files would break the hyperlink target in Github preview, but not in generated output.
• Stylesheets: The generated version is way more readable in the sense of providing good-looking defaults for fonts, spacing etc.
• Variables: Github has no conditional markup. We use that quite heavily already to remove duplications, to enforce a common root of all help system URLs, to include some parts multiple times etc.
• ... (probably more, these are just out of my head)

Given that the configuration is relative small and the processing time is in the order of seconds, I'd really not like to give up all these benefits.