I am using Spring RestDoc together with AsciiDoc to describe my rest api. RestDoc generates different files depending if there are request parameters described / response fields etc. I would like to have one template conditionally including whatever file exists.
something like this:
Request:
include::{reqresPath}/http-request.adoc[]
Response:
include::{reqresPath}/http-response.adoc[]
Parameters:
ifeval::[{{reqresPath}/request-parameters.adoc}.exists]
include::{reqresPath}/request-parameters.adoc[]
endif::[]
ifeval::[{{reqresPath}/request-parameters.adoc}.exists]
include::{reqresPath}/request-parameters.adoc[]
endif::[]
or at least exclude warnings in case of a missing file. But I could not figure out how to suppress these.
As of today, where is no operator for ifeval available, which can be used to check the existence of a file.
The way I would go is to write an extension for Asciidoctor, which can also be done by using Java. If your projects is big enough, I would suggest to go for this solution.
The most extreme way is to make a custom TemplatedSnippet which is generating an empty snippet to be included...
I hope there is a better way to do this.
Edit:
Take a look of http://asciidoctor.org/docs/user-manual/#by-tagged-regions
Related
I'm working on a project where YAMLs are used (among other use cases) for storing synonym lists. A file may look a little like this:
- "streifen,gestreift"
- "fleeceoverall,fleeceanzug"- "federball,badminton"
- "hochgarage,parkgarage"
In this case - "federball,badminton" is on the same row as - "fleeceoverall,fleeceanzug" which causes the build of the application to fail with an error stating
Unexpected characters near "- "federball,badminton".
I tried to configure a code style profile for code inspections as mentioned here in the PhpStorm documentation:
https://www.jetbrains.com/help/phpstorm/customizing-profiles.html?keymap=secondary_default_for_macos
But I don't know what to adjust here. I using the IDE-Standard which looks like this for wrapping and braces (which I guess is what I'm looking for ;) :
I also took a look at validating my YAML against a JSON file as mentioned here: https://www.jetbrains.com/help/phpstorm/yaml.html# but ultimately I don't understand how this works :/
So I guess I'm a little lost on how to avoid the errors at build time beforehand and would love some advice!
There must exist some application to do the following, but I am not even sure how to google for it.
The dilemma is that we have to backtrace defects and in doing so this requires to see how certain fields in the output xml have been generated by the XSL. The hard part is spending hours in the XSL and XML trying to figure out where it was even generated. Even debugging is difficult if you are working with multiple XSL transformation and edits as you still need to find out primary keys that get in the specific scenario for that transform.
Is there some software program that could take an XSL and perhaps do one of two things:
Feed it an output field name and it would generate a list of all
the possible criteria that would generate this field so you can figure out which one of a dozen in the XSL meets your criteria, or
Somehow convert the xsl into some more readable if/then type
format (kind of like how you can use Javadoc to produce readable documentation)
You don't say what tools you are currently using. Tools like oXygen and Stylus Studio have some quite sophisticated XSLT debugging capability. OXygen's output mapping tool (see http://www.oxygenxml.com/xml_editor/working_with_xslt_debugger.html#xsltOutputMapping) sounds very like the thing you are asking for.
Using schema-aware stylesheets can greatly ease debugging. At least in the Saxon implementation, if you declare in your stylesheet that you want the output to be valid against a particular schema, then if it isn't, Saxon will tell you what instruction in the stylesheet caused invalid output to be generated. Sometimes it will show you the error at stylesheet compile time, before you even supply a source document. This capability is greatly under-used, in my view. More details here: http://www.stylusstudio.com/schema_aware.html
It's an interesting question. Your suggestions are also interesting but would be quite challenging to develop; I know of no COTS or FOSS solution to either, but here are some thoughts:
Your first possibility is essentially data-flow analysis from
compiler design. I know of no tools that expose this to the user,
but you might ask XSLT processor developers if they have ever
considered externalizing such an analysis in a manner that would be useful to XSLT
developers.
Your second possibility is essentially a documentation generator
against XSLT source. I have actually helped to complete one for a client in
financial services in the past (see Document XSLT Automatically), but the solution was the property of
the client and was never released publicly as far as I know. It
would be possible to recreate such a meta-transformation between
XSLT input and HTML or Docbook output, but it's not simple to do in the
most general case.
There's another approach that you might consider:
Tighten up your interface definition. In your comment, you mention uncertainty as to whether a problem's source is bad data from the sender or a bug in the XSLT. You would be well-served by a stricter interface definition. You could implement this via better typing in XSD, addition of xsd:assertion statements if XSD 1.1 is an option, or adding a Schematron-based interface checking level, which would allow you the full power of XPath-based assertions over the input. Having such an improved and more specific interface definition would help both you and your clients know what should and should not be sent into your systems.
I am using asciid for an article. In the end of my document I want to have a list of figures. How to I create a list of figures? Did not find something useful in the documentation for me.
Nope there isn't one at the time of answer. I checked the docs (which you indicated you did as well) and I also grepped the codebase. There is good news though! You should be able to do this with an extension.
Extensions can be written in any JVM language if you're using asciidoctorj, or in Ruby if you're using the core asciidoctor (I'm not sure about JavaScript for asciidoctorjs). You'll need to create two extensions probably: a TreeProcessor extension to go through the whole AST looking for images and pulling them out into a storage structure. Then you'll also need to create either an inline or block macro to actually place it within the page.
I strongly recommend examining the API for the nodes and functions you'll want to make use of. There are some other examples of processors that may also be helpful to examine.
Say I want to consume an API that returns JSON-LD and follow all the links. (I'm experimenting with the Hydra API-Demo, but it should work with all JSON-LD APIs, not only Hydra-based ones. Any good APIs out there that I should try?)
So I want to follow all the links and my environment doesn't have native RDF support. Probably, I should first parse it with one of the libs and get it into extended form with jsonld.expand(). Then I just grab all the values with key #id. Is that the recommended way to do it or am I missing some edge-cases?
The purpose of the expansion API is to produce regular, context-free output (expanded form) for algorithmic processing -- which is exactly what it sounds like you want to do. So, yes, you've got the right approach; you shouldn't be missing any edge cases as I've understood you. After you have JSON-LD in expanded form, you can easily follow the #ids (and, if you also need to do some kind of analysis of the vocabulary/ontology, you can follow the properties which will then be fully-expanded URLs).
I am getting data from a broken RSS feed that gives me wrong link. I wanted to fix this link so I made this code:
<link.*>(.*)&.*tid(.*)</link>
and the link could be like:
www.somedomain.com/?value=50&burrrdurrrr;tid=120
But the real working link is in this form:
www.somedomain.com/?value=50&tid=120
The thing that I'm asking is if my measure thing looks like this:
[FeedURL]
Measure=Plugin
Plugin=Plugins\WebParser.dll
Url=[Feed]
StringIndex=2 ;now I only get www.somedomain.com/?value=50
Substitute=#SubstituteFeed#
How am I supposed to concatenate the strings together to complete the url?
I'm guessing rather than &burrrdurrrr;, the link has &, which is how you have to write & in an HTML or XML file.
If that's the case, you just need to set the DecodeCharacterReference option, as described in this handy-looking tutorial. Another option mentioned there is Substitute, which would be able to strip it out even if it really was &burrrdurrrr;.
None of this is a particularly sensible way of dealing with HTML or XML - a much better approach would be a plugin which actually parsed the document structure and let you reference nodes using XPath or CSS rules - but you work with what you've got, I guess. (I've never heard of this "Rainmeter" before, despite its claim to be "the best known and most popular desktop customization program for Windows"; maybe because nobody else calls their program that, instead almost universally using the word "widget"?)