Ascii-doc/Markdown has 'Introduction' as title, and all sections as subsections

[oliv3r]

Currently, the header 'Introduction and goals' has a single hash (#) to indicate it's a top-level header. 'Requirements and overview' however has the second level header, as well as all following chapters. That means, that when looking at the template from a tree point of view (like for example also when using the sometimes supported __TOC__ marker to generate a table of contents, we end up with

• Introduction and goals
  |
  +- Requirements and overview
  |
  +- Quality goals
  ...

which makes it weird to read/look at the document.

Instead, the single hash should be used for a (placeholder in the template) document title, and 'Introduction and goals' should be on the second level, like all other headers.

E.g.

# <Project> architecture document (ARC42 template based) {#_document_title}
[optional for supported renders] __TOC__

## Introduction and goals  {#section-introduction-and-goals}
...

## Requirements Overview {#_requirements_overview}
...

[rdmueller]

Thanx for reporting this issue.

The markdown version is generated from the AsciiDoc version. Can you trace this problem back to the AsciiDoc version? This would help a lot.

[Hruschka]

Ralf, Please don‘t change the hierarchy. Requirements overview and Quality Goals are deliberately subsection of the Intro to the Architecture. Peter Von meinem iPhone gesendet

…

Am 09.05.2022 um 18:15 schrieb Ralf D. Müller ***@***.***>:  Thanx for reporting this issue. The markdown version is generated from the AsciiDoc version. Can you trace this problem back to the AsciiDoc version? This would help a lot. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you are subscribed to this thread.

[gernotstarke]

It's not the hierarchy itself that's wrong, but the start of the hierarchy:

Imho the document title should be a title ABOVE the underlying hierarchy, and in our markdown version it seems to be wrong.

In Markdown, it should be:

Document title

Introduction and goals

- Requirements and overview

Quality goals

Constraints

Context and Scope

...

Cannot investigate today, sorry...

[oliv3r]

@gernotstarke

You are correct, My example was bad; @hrushka, I do think it should be changed, but I do appologize for using the wrong example, which was probably amplified exactly because of this bug :)

@rdmueller I'm not sure I can pin-point it in the ascii-doc. There, the introduction IS at 'level 2' https://github.com/arc42/arc42-template/blame/master/EN/asciidoc/src/01_introduction_and_goals.adoc#L2 here, but I think when the markdown gets generated, somehow it gets promoted to 'L1' for some reason. So in that case, the bug would be at generation time? No idea how it gets generated, but having a 'Dummy' title placeholder in the ascii doc as well, could resolve it, which practically it is (the arc42 logo + text. https://github.com/arc42/arc42-template/blame/master/EN/asciidoc/arc42-template.adoc#L6

Btw, looking more closely, it actually even seems all headers are 'off by one' as everything is a title ...

In the single page document it's even 'worse' in that there IS a title, but it's blank, but does suffer from the same issue, where each chapter is a title.

[rdmueller]

just to clarify the levels... afaik, in AsciiDoc speak, == is Level 1 and = is level 0 which is the document or book title. Level 0 should only exist once per document. That's why all chapters start with ==.

the code which converts the AsciiDoc template to markdown can be found here:

https://github.com/arc42/arc42-generator/blob/master/subBuild.gradle#L185

as you can see, pandoc is used.