Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

grammar fixes #28

Merged
merged 1 commit into from
Jan 30, 2024
Merged

grammar fixes #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .vscode/settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{}
37 changes: 18 additions & 19 deletions src/a_few_basics.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,30 @@
[[a_few_basics]]
== A few AsciiDoc basics

AsciiDoc is fully documented, and its documentation is actively maintained. This document contains some information on asciidoc markup to get you started.
AsciiDoc is fully documented, and its documentation is actively maintained. This document contains some information on AsciiDoc markup to get you started.

For details and additional options, see:

* Asciidoc/asciidoctor https://asciidoctor.org/docs/asciidoc-writers-guide/[writers' guide].
* Asciidoc http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[quick reference].
* AsciiDoc/Asciidoctor https://asciidoctor.org/docs/asciidoc-writers-guide/[writers' guide].
* AsciiDoc http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[quick reference].
* Asciidoctor http://asciidoctor.org/docs/user-manual/[user manual].

In addition, you have the option of asking questions in the asciidoctor discussion list:
In addition, you can ask questions in the https://discuss.asciidoctor.org/[Asciidoctor discussion list].

As is true of any complex process, asciidoc/asciidoctor has some quirks. Please be certain to make use of these templates because they provide you with files that will result in fully featured pdf output.
As is true of any complex process, AsciiDoc/Asciidoctor has some quirks. Please be certain to use the templates, as the templates provide you with files that result in fully featured PDF output.

Best practice is to test the pdf build frequently to ensure that you have not accidentally introduced something that breaks the build.
Best practice is to test the PDF build frequently to ensure that you have not accidentally introduced something that breaks the build.

WARNING: PDF generation currently requires the use of Ruby 2.7.2.

[NOTE]
====
Please feel free to send questions to [email protected]
Please feel free to send questions to [email protected].
====

=== Paragraphs

In AsciiDoc, normal paragraphs require no markup at all.
In AsciiDoc, normal paragraphs do not require markup.

==== Basics of blocks and indents

Expand All @@ -37,7 +37,7 @@ Add a `+` directly above the line of text that you want to be indented within th
+
Using the `+` to create an indented paragraph only works within the context of a numbered or bulleted list.

Asciidoc/asciidoctor supports code blocks with syntax highlighting for many languages. You can use either periods or dashes to indicate code blocks, and use macros to indicate that the block contains code in the specified language, as in the following example:
AsciiDoc/Asciidoctor supports code blocks with syntax highlighting for many languages. You can use either periods or dashes to indicate code blocks, and use macros to indicate that the block contains code in the specified language, as in the following example:


[source,adoc]
Expand All @@ -49,21 +49,21 @@ add a1,a2,a3; # do an ADD
....
----

renders as follows:
This example renders as follows:

[source,python]
----
mono-spaced code block
add a1,a2,a3; # do an ADD
----

See <<blocks_notes_markers>> for additional information on blocks.
See <<blocks_notes_markers>> for additional information about blocks.

=== Headers

While authoring in asciidoc, you cannot jump directly from a Head 1 to a Head 3 or 4. Your headers must appear in sequence from Head 1 to Head 2, and onward. If you skip over a header in the sequence, asciidoctor throws an error.
When you author in AsciiDoc, you cannot jump directly from a Head 1 to a Head 3 or 4. Your headers must appear in sequence from Head 1 to Head 2, and onward. If you skip over a header in the sequence, Asciidoctor throws an error.

Following is an example of a valid sequence of headers.
The following example is a valid sequence of headers.

```adoc
= Title head (book or report title)
Expand Down Expand Up @@ -118,19 +118,18 @@ Use macros for cross references (links within a document) as in the following ex
<<Index markers>> describes how index markers work.
----

This renders as:
This example renders as:

<<Index markers>> describes how index markers work.


The `book_header.adoc` file in the docs-templates repo sets the `full` cross reference attribute to enable the display of captions from targets in the anchors. This allows you to set captions for tables, blocks, and illustrations. If no caption is provided, Asciidoctor defaults to the _basic_ cross reference style.
The `book_header.adoc` file in the docs-templates repo sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. This ability allows you to set captions for tables, blocks, and illustrations. If you do not provide a caption, Asciidoctor defaults to the _basic_ cross reference style.

To set a caption for a table or image, use the pattern as follows:

[source,adoc]
----
The table below, <<trapcharacteristics,Characteristics of traps>> shows the characteristics of each
kind of trap.
The following table, <<trapcharacteristics,Characteristics of traps>> shows the characteristics of each kind of trap.
----

[source,adoc]
Expand All @@ -146,7 +145,7 @@ kind of trap.
|===
----

The table below, <<trapcharacteristics>> shows the characteristics of each
The following table, <<trapcharacteristics>> shows the characteristics of each
kind of trap.

[[trapcharacteristics]]
Expand Down Expand Up @@ -180,6 +179,6 @@ sqrt(4) = 2

In some cases, you might want to make use of unicode characters. Keep in mind that asciidoctor-pdf currently only supports decimal character references. See https://github.com/asciidoctor/asciidoctor-pdf/issues/486

Hexadecimal unicode looks like it has problems in the pdf. This is gnarley.
Hexadecimal unicode looks like it has problems in the PDF. This is gnarley.

Updates to asciidoctor-pdf: https://github.com/asciidoctor/asciidoctor-pdf
34 changes: 16 additions & 18 deletions src/authoring.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
== Asciidoc authoring for RISC-V contributors
== AsciiDoc authoring for RISC-V contributors

As a contributor to RISC-V, your contributions will likely be in one of the two following categories:

* adding content to an existing specification.
* creating an entirely new specification.
* Adding content to an existing specification.
* Creating an entirely new specification.

In either case, please feel free to examine the AsciiDoc source files for this `example.pdf` and adapt the markup for your use.

Expand All @@ -19,11 +19,11 @@ There are three major Asciidoctor toolchains:

=== RISC-V AsciiDoc authoring assets

Please view the readme in the https://github.com/riscv/docs-templates[docs-templates repo] for information on automated build processes.
Please view the https://github.com/riscv/docs-templates[readme] in the docs-templates repo for information about the automated build processes.

The above mentioned repo also contains assets (fonts, styles, directory structure, and themes) that you need for RISC-V specifications, along with a https://github.com/riscv/docs-templates/commit/5c18cc9761eb3f6516975ee0c109729a4ce66b93[document] that takes you through a local install process that supports all of the needed features for a local build.
The docs-templates repo also contains assets, such as fonts, styles, directory structure, and themes that you need for RISC-V specifications, along with a https://github.com/riscv/docs-templates/commit/5c18cc9761eb3f6516975ee0c109729a4ce66b93[document] that takes you through a local install process that supports all of the required features for a local build.

Although testing your markup by building a pdf is good practice, you can catch many common errors by simply downloading Asciidoctor and building the HTMl5 output using the following command:
Although testing your markup by building a PDF is good practice, you can catch many common errors by simply downloading Asciidoctor and building the HTMl5 output using the following command:

[source,cmd]
----
Expand All @@ -32,18 +32,18 @@ asciidoctor book_header.adoc

=== Simply writing

To begin authoring in AsciiDoc, all you need is a text editor. <<editors>> lists editors that support authoring in AsciiDoc.
To begin authoring in AsciiDoc, select a text editor. <<editors>> lists the editors that support authoring in AsciiDoc.

A quick reference for AsciiDoc markup: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/. Most of the markup that you will need is simple, and will have a familiar feel to people who have used git-flavored Markdown. For RISC-V specifications, it is the procedures for <<graphics>> that add complexity.
For quick reference, see https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference]. Most of the markup for the specifications is simple and have a familiar feel to people who have used Git-flavored Markdown. For RISC-V specifications, it is the procedures for <<graphics>> that add complexity.

The https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Writers Guide] contains details about AsciiDoc markup. For pdf generation, you can find details at https://github.com/asciidoctor/asciidoctor-pdf#install-the-published-gem[asciidoctor-pdf].
The https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Writers Guide] contains details about AsciiDoc markup. For PDF generation, you can find details at https://github.com/asciidoctor/asciidoctor-pdf#install-the-published-gem[asciidoctor-pdf].

[[editors]]
==== Text editors that support AsciiDoc authoring

I have not yet encountered a true wysiwyg editor for asciidoc. However, there are live preview options listed in the https://docs.asciidoctor.org/asciidoctor/latest/tooling/[Asciidoctor documentation]. You might want to use your favorite text editor, or perhaps switch to one that has good asciidoc linting.
There isn't a true WYSIWYG editor for AsciiDoc. However, there are live preview options that are listed in the https://docs.asciidoctor.org/asciidoctor/latest/tooling/[Asciidoctor documentation] that can help you see what the output looks like. You can also use your favorite text editor, or perhaps switch to one that has good AsciiDoc linting.

The following list contains links to resources for text editor/IDE support of asciidoc:
The following list contains links to resources for text editor/IDE support of AsciiDoc:

* Information on helpful https://docs.asciidoctor.org/asciidoctor/latest/tooling/[AsciiDoc tools that integrate with several popular IDEs]
* https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[VS]
Expand All @@ -55,13 +55,11 @@ The following list contains links to resources for text editor/IDE support of as
* https://alldocs.app/convert-openoffice-odt-to-asciidoc[OpenOffice]--it’s possible to start by authoring in OpenOffice and then output to asciidoc, and you can https://github.com/dagwieers/asciidoc-odf[go the other way]
* https://www.asciidocfx.com/[AsciidocFX]

We received a request for information on ghostwriter and found that while it does support Markdown, it does not at this time support AsciiDoc.
While ghostwriter does support Markdown, it does not support AsciiDoc at this time.

=== An asciidoc primer and more
=== An AsciiDoc primer and more

Much of what you need to know about the asciidoc toolchain that we are using, including install procedures, is online in the

https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDOc Writers' Guide]
Much of what you need to know about the AsciiDoc toolchain used for RISC-V, including installation procedures, is online in the https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Writers' Guide].

Here are a few additional, useful links:

Expand All @@ -71,11 +69,11 @@ Here are a few additional, useful links:

[NOTE]
====
The best linter for asciidoc is available for Sublime Text, and linters are available for other popular text editors as listed above.
The best linter for AsciiDoc is available for Sublime Text, and linters are available for other popular text editors as previously listed.
====

==== Build often

As soon as you have installed asciidoctor on your computer, you have the ability to check that each individual file builds in html by simply running `asciidoctor filename.adoc` on any file. You can also check that the book or report on which you are working builds in html by running `asciidoctor bookname.adoc` or `asciidoctor reportname.adoc` on the book or report header. The strings `filename`, `bookname`, and `reportname` all should be replaced with the actual names you are using.
As soon as you install Asciidoctor on your computer, you can check that each individual file builds in HTML by running `asciidoctor filename.adoc` on any file. You can also check that the book or report on which you are working builds into HTML by running `asciidoctor bookname.adoc` or `asciidoctor reportname.adoc` on the book or report header. The strings `filename`, `bookname`, and `reportname` all can be replaced with the actual names that you are using.

Asciidoctor has fairly good error messages and usually lets you know the file and row number where the build first breaks.
Loading