Comments (11)
I've started work on a plugin for textlint so we can leverage the validation ecosystem already available. It just requires creating a new parser for AsciiDoc that can be hooked into that framework. You can find an early prototype here: https://github.com/opendevise/textlint-plugin-asciidoc This will converege with the work @Mogztter has been doing on a new inline parser for AsciiDoc at https://github.com/Mogztter/asciidoctor-inline-parser. It's still early days, but things are starting to move.
from asciidoctor-extensions-lab.
A tool like markdownlint would be awesome !
from asciidoctor-extensions-lab.
We are absolutely on the same page about this. This topic has come up many times in the past, to which I've replied, "yes, we should definitely have a validator extension that does this". I'm so glad you filed the issue, because I keep forgetting to do it.
We're working on bringing over a set of best practices from documents we created for NFJS, the Magazine authors. Currently, that content lives here: https://github.com/nofluffjuststuff/nfjsmag-docs/blob/master/author-writing-style-and-syntax-guide.adoc
from asciidoctor-extensions-lab.
I'm so glad you filed the issue, because I keep forgetting to do it.
Anytime, if you need some more work I can think of many more things !! Just kidding, I will gladly help 😉
I missed the extension API part in the 0.1.4 release but I see a lot of possibilities and it's a pleasure to prototype things...
from asciidoctor-extensions-lab.
I'm quite interested in this as well. A range of conventions could be checked. The conventions that are useful to check range from requiring simple up to technically difficult checks. E.g. checking whether the rendering of document happens with certain attributes set would be less difficult than finding incorrectly marked up hyperlinks. Finding unavailable hyperlinks would be easier than finding suboptimal heading structure.
Since documentation is normally part of a software release engineering process and should meet the concomitant QA criteria, it is natural to automatically run linters in addition to code linters.
from asciidoctor-extensions-lab.
@mojavelinux: what would be the way to go about programming such a linter? Would it best use an extension point?
from asciidoctor-extensions-lab.
@sanmai-NL Very likely a hybrid approach will be needed. To check the content, such as broken links, I might parse the document to the AST and examine it from there (a treeprocessor). Since inline parsing occurs during conversion, it might be necessary to look at the final output (a postprocessor). To check syntax, we're likely going to need to look at the raw text (a preprocessor). However, the preprocessor is tricky since it isn't aware of the document structure and lacks a lot of context.
So it really depends on what you want to focus on. My recommendation is to set some goals and then to try to find ways to accomplish those goals. Little by little, we'll have a linter framework.
from asciidoctor-extensions-lab.
As I have stated elsewhere, after doing some analysis, I came to realize that it's not feasible or even sensible for the parser that handles conversion to also provide a framework for validation. These are very different concerns and should be handled with discrete tools. The reason is, a validator needs to know stuff about the document that the converter doesn't care about. And it needs to seek for things that the converter doesn't need or want to look for. So the validator would make the converter do a lot of extra work just for the purpose of validation. And the opposite is true as well. It's better that these tools evolve independently.
I'll give one example to give you an idea how I came to this conclusion. Consider the case of a missing blank line between a paragraph and a list. The converter will happily treat this as a single paragraph. But to the writer, this is an error. The list is not being recognized. But technically, nothing is wrong with the document. Maybe that is what the author intended. So a validator can use a rule to look for this type of syntax blunder, understand the intention, and suggest that a blank line is missing. That's just not something the converter should ever worry about. The converter is going to assume the document is correct and should be converted as is. If these tools can be allowed evolve independently, we can do a lot of these types of (optional) checks.
from asciidoctor-extensions-lab.
Checking can be done on the concrete syntax tree, whereas you are talking about the abstract syntax tree. Is there a grammar for Asciidoc(tor)? The linting tool can be implemented separately. Also, a more general linting tool could be made to operate on the HTML representation of technical documents.
from asciidoctor-extensions-lab.
Checking can be done on the concrete syntax tree, whereas you are talking about the abstract syntax tree.
Because that's where I think it needs to be checked to be any good.
The linting tool can be implemented separately.
Exactly what I'm saying. But it will still need a parser implementation, which is what the textlint extension is for.
Is there a grammar for Asciidoc(tor)?
Not yet. The effort is picking up momentum though.
a more general linting tool could be made to operate on the HTML representation of technical documents.
Such tools already exist. See vale for one example. The problem I have with that approach is that there's no visibility into where the problem stems from in the AsciiDoc source, so it doesn't scale to large documentation sets.
from asciidoctor-extensions-lab.
A lint extension is not feasible. It needs to be a separate parser. The Asciidoctor parser is focused on parsing a valid AsciiDoc document and therefore doesn't capture all the information needed for a linter. I have linked to prototypes above. We could focus on developing those further, though they have a dependency on the AsciiDoc Language project producing a formal grammar on which that parsing can be based...and that work is still in progress.
from asciidoctor-extensions-lab.
Related Issues (20)
- Is there a configuration open for using divs instead of tables for admonitions? HOT 1
- mathoid-treeprocessor and new versions of mathoid HOT 4
- npm install mathoid error: Package libffi was not found in the pkg-config search path. HOT 2
- Convert all inline example to use create_inline otherwise it gives "INFO: expected substitution value for custom inline macro to be of type Inline" HOT 5
- Integrate asciidoc-coalescer.rb as extension/converter so as to make it available in the CLI HOT 1
- sectnum offset tree processor always returns 1 or 2 HOT 1
- Make all these extensions installable with gem install HOT 4
- Add list of tables and list of figures HOT 28
- generate pdf with chart block HOT 4
- adding row name to chart HOT 3
- Add a metadata object for year HOT 1
- Add metadata object for tag message HOT 2
- man-inline-macro doesn't generate the correct output in the manpage backend HOT 5
- Section offset plugin fails when creating PDF HOT 4
- Using the Preprocessor ignores ifdef directives HOT 1
- add link to the current script location as comment into the script HOT 6
- Idea: Create file tree containing all included files HOT 2
- Graduate the asciidoc-coalescer.rb script to a separate project HOT 4
- Add macro for GitHub / BaseCamp emoji library HOT 6
- Help With Callouts: Any Examples? HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from asciidoctor-extensions-lab.