AsciiDoc Language issueshttps://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/issues2023-03-10T23:02:32Zhttps://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/issues/24Summarize all available block style in one section2023-03-10T23:02:32ZHemang AjmeraSummarize all available block style in one section
Adding a list/table of all the style available in asciidoc will be useful in this page https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/blob/main/docs/modules/blocks/pages/index.adoc
Adding a list/table of all the style available in asciidoc will be useful in this page https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/blob/main/docs/modules/blocks/pages/index.adochttps://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/issues/23Include Content Model information for each context2023-03-10T23:03:36ZHemang AjmeraInclude Content Model information for each contextIt will be really useful for newbie like me to understand the content concept better if we can add third column in the table at https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/blob/main/docs/modules/blocks/pages/index.ad...It will be really useful for newbie like me to understand the content concept better if we can add third column in the table at https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/blob/main/docs/modules/blocks/pages/index.adoc#user-content-summary-of-built-in-contexts indicating context model (if a block is compound, simple, verbatim, raw, empty or table)https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/issues/21Document see and see-also indexterm attributes2023-02-28T22:49:42ZSarah WhiteDocument see and see-also indexterm attributes*Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/120*
In brief, the shorthand delimiter `>>` defines a see term and the shorthand delimiter `&>` defines one or more see also terms.
Here's an example of an index term...*Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/120*
In brief, the shorthand delimiter `>>` defines a see term and the shorthand delimiter `&>` defines one or more see also terms.
Here's an example of an index term with a see term (i.e., redirect):
```
(((Flash >> HTML 5)))
```
This is shorthand for:
```
indexterm:[Flash,see=HTML 5]
```
Here's an example of an index term with see also terms:
```
(((HTML 5 &> CSS 3 &> SVG)))
```
This is shorthand for:
```
indexterm:[HTML 5,see-also="CSS 3,SVG"]
```
Both attributes work with the visible index term as well (double round brackets or indexterm2 macro).
There can only be one "see" term. There can be multiple "see also" terms.https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/issues/20Consolidate and clarify anchors and ID end user documentation2023-02-28T19:45:08ZSarah WhiteConsolidate and clarify anchors and ID end user documentationThe end user documentation regarding anchors and IDs needs to be consolidated and clarified as some users have expressed that the concepts of ID and anchor could be better explained, that the information about where IDs can be placed and...The end user documentation regarding anchors and IDs needs to be consolidated and clarified as some users have expressed that the concepts of ID and anchor could be better explained, that the information about where IDs can be placed and the syntax for such use cases should be consolidated, and that more and/or better examples would be helpful.
This issue should:
- identify what areas of the anchor and ID end user documentation needs to be clarified (restructured, reworked, more search-friendly, direct headings, etc.)
- restructure and edit the anchor and ID content that is problematic
- make sure that the exceptions and recommendations for each syntax and/or use case is clearly stated
- add new content and/or new examples for any anchor and ID use cases
This issue was created based on a PR and the discussion referenced in the PR: https://github.com/asciidoctor/asciidoc-docs/pull/106
This issue may have some cross over with #19.https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/issues/19Clarify and expand xref macro end user documentation2023-02-28T19:45:46ZSarah WhiteClarify and expand xref macro end user documentation*Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/79*
Some users are having difficulty finding the documentation about how to use the xref macro (both the shorthand and named version), determining when they should use...*Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/79*
Some users are having difficulty finding the documentation about how to use the xref macro (both the shorthand and named version), determining when they should use which form, and what options and attributes are associated with the xref macro.
This issue should:
- identify what areas of the xref end user documentation needs to be clarified (restructured, reworked, more search-friendly, direct headings, etc.)
- restructure and edit the xref content that is problematic
- add new content and/or new examples for any undocumented xref options, attributes, or common use cases
The existing xref documentation pages are:
- Cross References: https://docs.asciidoctor.org/asciidoc/latest/macros/xref/
- Document to Document Cross References: https://docs.asciidoctor.org/asciidoc/latest/macros/inter-document-xref/
- Cross Reference Text and Styles: https://docs.asciidoctor.org/asciidoc/latest/macros/xref-text-and-style/
- Validate Cross References: https://docs.asciidoctor.org/asciidoc/latest/macros/xref-validate/https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/issues/18Add dedicated section or page for the linenums option on source blocks2023-02-28T19:15:19ZSarah WhiteAdd dedicated section or page for the linenums option on source blocks*Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/77*
Source blocks support the `linenums` option. This option adds line numbers to the rendered source block when supported by the source highlighter or converter.
```...*Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/77*
Source blocks support the `linenums` option. This option adds line numbers to the rendered source block when supported by the source highlighter or converter.
```asciidoc
:source-highlighter: rouge
[source%linenums,js]
----
function fib (n) {
if (n < 2) return n
return fib(n - 1) + fib(n - 2)
}
console.log([1, 2, 3, 4, 5].map(fib))
----
```
The `linenums` option can also be specified as the third positional (unnamed) attribute on the source block.
```asciidoc
:source-highlighter: rouge
[source,js,linenums]
----
function fib (n) {
if (n < 2) return n
return fib(n - 1) + fib(n - 2)
}
console.log([1, 2, 3, 4, 5].map(fib))
----
```
However, the named option is preferred. The option can also be enabled globally by setting the `source-linenums-option` attribute.
The docs should emphasize that while the option is a part of the AsciiDoc language, it does require support from the toolchain (syntax highlighter adapter, converter, and/or output format), so it may not always be honored.
The `linenums` option is documented in passing in the Asciidoctor docs on the page for each syntax highlighter adapter. See:
* https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/pygments/
* https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/rouge/
* https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/coderay/
However, this topic deserves its own section or page to define it and solidify it as part of the AsciiDoc language.https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/issues/17Add top-level Document section to documentation site navigation2023-02-28T19:11:54ZSarah WhiteAdd top-level Document section to documentation site navigation*Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/10*
The document is such a foundational concept in AsciiDoc that it deserves its own top-level section in the nav. In the end user documentation, this section is the n...*Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/10*
The document is such a foundational concept in AsciiDoc that it deserves its own top-level section in the nav. In the end user documentation, this section is the natural place for the pages about the document type and document header to live. (It's possible that the pages about document attributes could live here, though they are arguably so universal that they still deserve their own top-level section).
Here's the proposed layout:
- Document
- Document Type
- Document Header
Document is also a central concept in the API, so having a place to link might make writing about the API easier.https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/issues/14Section style should be framed as a special section2023-02-28T01:55:15ZSarah WhiteSection style should be framed as a special section*Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/5*
When a section title has a style (e.g., `preface`, `appendix`, `glossary`, etc.), it automatically makes that section a special section. The documentation should in...*Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/5*
When a section title has a style (e.g., `preface`, `appendix`, `glossary`, etc.), it automatically makes that section a special section. The documentation should introduce the term "special section" and explain this correlation.
Also, do we need separate pages for [Dedication](https://docs.asciidoctor.org/asciidoc/latest/sections/dedication/) and [Colophon](https://docs.asciidoctor.org/asciidoc/latest/sections/colophon/)? Except for a handful of exceptions, special sections are just a passthrough designation (What does a passthrough designation actually mean?). For any special section style that AsciiDoc doesn't apply special meaning, they should be grouped on the Special Sections page and just listed. These include: colophon, dedication, acknowledgements. We may also point out that technically the list is open ended. It's up to the discretion of the converter to handle any additional names.https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/issues/13Add a dedicated page that covers the AsciiDoc table cell style2023-02-28T01:43:31ZSarah WhiteAdd a dedicated page that covers the AsciiDoc table cell style*Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/75*
The AsciiDoc table cell style deserves it's own page. Currently it is only documented as a section on the following page:
*Published page: https://docs.asciidocto...*Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/75*
The AsciiDoc table cell style deserves it's own page. Currently it is only documented as a section on the following page:
*Published page: https://docs.asciidoctor.org/asciidoc/latest/tables/format-cell-content/*
*Source page: https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/blob/main/docs/modules/tables/pages/format-cell-content.adoc*
Unlike the other table cell styles, it actually changes how the content is parsed. And there are some things to know about it.
- The AsciiDoc table cell must be used if the content contains AsciiDoc block content (paragraph, listing block, etc); it is not needed if the cell only has inline formatting
- An AsciiDoc table cell is an embedded document
- An AsciiDoc table cell inherits attributes from the parent document (though there are some exceptions)
- Line comments are removed from the content before the table cell is parsed (unlike a normal AsciiDoc document)
- The content should begin on a new line (though this is just a recommendation atm)
- References are shared with the parent document
- Counters are shared with the parent document
- Footnotes are processed independently from the parent document
This issue would include moving the content (or reconciling and removing the content) from the source page linked to above, particularly the [a operator section](https://docs.asciidoctor.org/asciidoc/latest/tables/format-cell-content/#a-operator) as well as adding some important terminology (most notably "AsciiDoc table cell") and context (when do I need it, when do I not need it).