I'm using Ascii doc to make rest documentation with Spring Restdocs. I have an overview section and then a section with operations. I want the operations to have numbered sections, but I don't want the overview and other sections to be included in the numbering. Also, I'd like to not have the "operations" header have a number, because that's the only section that's numbered, so it makes little sense.
So, what I have is something like this:
= Web service title header
[preface]
== Overview
overview text
=== Overview sub section 1
stuff
=== Overview sub section 2
more stuff
== Operations
:sectnums:
include::oauth2-scopes.adoc[]
include::oauth2-clients.adoc[]
And then controller-1.adoc looks like this:
=== OAuth2 Scopes
==== Get scope
operation::get-scope[]
==== Get all scopes
operation::get-all-scopes[]
When this is rendered, the structure itself is great, the sections inside of "operations" are numbered. But, the problem is that the numbers are weird.
It seems the "operation" header is forced to be numbered one, even though there's no number there and the subsequent numbers seem to know that the number is suppressed.
I hope that this is enough to go by. I'm not super experienced with Asciidoc, so I may be missing something.
I've thought of using a multilevel numbered list, but I want it rendered as headers with anchors, not just a regular list.
Edit: I'm working around it by putting the heading "Operations" and the same level as the included sections (level 2). This makes the TOC indentation off, but it's less distracting than the numbers being messed up.
Edit 2: I was wanting Operations to be at level two (==) and the name of the controller to be level three (===). I want the controllers to be numbered. It doesn't make much sense to have the section title be numbered 1 and then the things I actually want enumerated to be numbered 1.1.
I am not sure if I understand your question correctly.
If you need to optimise the weird numbering, make sure to reduce the level (from === to == etc.) This will fix that.
If you want to switch off the numbering at some point, set a ":sectnums!:" at the needed postition.
But if I am completely on the wrong track, please try to reformulate your question. And if you add a screenshot, please make sure it fits to your example ;-)
Related
I'm using data from synthea and it looks like most (all?) of the given and family names I'm getting back end with a three digit number (e.g. Gregg522). Is this part of the design of synthea or am I parsing the data incorrectly. A snippet of the json I'm getting back is shown below. If this is part of the design, what is the motivation of ending the name with a number (I would think this would make the data less realistic).
Yes, they generally do. It is sometimes nice to be able to see that the patients are fake/synthetic ones. However, this is a setting you can change: In the synthea.properties file, look for the setting "append_numbers_to_person_names" and set it to false.
I'm currently learning webfocus and I'm learning about defining, but what is teaching me isn't doing a great job. An example that has been given to me is about cars. If I want to make a new field to find the difference between the retail cost and the dealer cost, they said to input
DEFINE FILE CAR
CALCULATED_DIFFERENCE/D5 = RETAIL_COST - DEALER_COST
END
What I'm confused about is what the
/D5
is there for. Is it required to define a file? Does it have to be something specific? I've researched a lot but haven't found any answers about it.
From what I understand, it joins the aliases and roots. For example the D could be short for difference. The 5 could just be a number. Without all of the example and question it's hard to say.
Here is another example http://www.hwconline.com/ibi_html/javaassist/intl/EN/help/source/topic547.htm
Section
A preceding forward slash '/' is required for all aliases and context roots. The WebFOCUS Administration Console automatically adds a forward slash if one was not entered.
I am assuming it could be a pointer. Look at the url and the / indicates like a tree node. If you want to get to a location then it's location/location/location/here
here being what your looking at. So if the /D5 is called it could mean page/page/page/Difference5 so for short it omits all of the pages and signifies the direct alias D5.
I am not entirely sure but that is what I have always thought. Look at everything dealing with locations a \ or / is always used.
I've found out what it means. The /D5 is known as formatting. It allows WebFOCUS to know what is being used in the file. The D stands for decimal, which means that if I wanted to I could format it as D/5.2 and an A stands for alphanumeric. If I were to define a file called person_last_name, I would use A/30. The number determines how much data it can hold, so 30 is all I need as a person's last name probably won't be longer than 30 characters.
I've got a rather large asciidoc document that I translate dynamically to PDF for our developer guide. Since the doc often refers to Java classes that are documented in our developer guide we converted them into links directly in the docs e.g.:
In this block we create a new
https://www.codenameone.com/javadoc/com/codename1/ui/Form.html[Form]
named `hi`.
This works rather well for the most part and looks great in HTML as every reference to a class leads directly to its JavaDoc making the reference/guide process much simpler.
However when we generate a PDF we end up with something like this on some pages:
Normally I wouldn't mind a lot of footnotes or even repeats from a previous page. However, in this case the link to Container appears 3 times.
I could remove some of the links but I'd rather not since they make a lot of sense on the web version. Since I also have no idea where the page break will land I'd rather not do it myself.
This looks to me like a bug somewhere, if the link is the same the footnote for the link should only be generated once.
I'm fine with removing all link footnotes in the document if that is the price to pay although I'd rather be able to do this on a case by case basis so some links would remain printable
Adding these two parameters in fo-pdf.xsl remove footnotes:
<xsl:param name="ulink.footnotes" select="0"></xsl:param>
<xsl:param name="ulink.show" select="0"></xsl:param>
The first parameter disable footnotes, which triggers urls to re-appear inline.
The second parameter removes urls from the text. Links remain active and clickable.
Non-zero values toggle these parameters.
Source:
http://docbook.sourceforge.net/release/xsl/1.78.1/doc/fo/ulink.show.html
We were looking for something similar in a slightly different situation and didn't find a solution. We ended up writing a processor that just stripped away some of the links e.g. every link to the same URL within a section that started with '==='.
Not an ideal situation but as far as I know its the only way.
My wording for this question might not be specific enough, but here's a little more context...
When looking for a block in cache, the controller selects the set first. Then does it,
1) Test all valid bits in selected set and "return" a cache miss if any valid bits are not set to 1
or
2) Find the line with a matching tag bit and THEN check the valid bit for just that line.
I understand everything else relating to this process. I'm just a little confused on what comes first, finding the line or testing valid bit(s). Thanks in advance!
An implementation could either 1) find the right line then check if it's valid or 2) find all valid lines and see if the right line is among them, or 3) find all valid lines and the right line in parallel and see if the two results intersect. There may even be other approaches, like considering the valid bit to be an extra bit in the tag and searching for that augmented tag... The end result would be the same, and the specific choice the implementers made isn't generally documented in publicly available documentation, but may be available in design documentation, if they can be persuaded to reveal it.
Internalization in Play2 can be done with Message.get("home.title") and language files. What about when you internalizate a page full of textual content and not just one specific header or link?
For example doing Messagefile for a long page representing e.g. product info:
_First header_
Some paragraphs of text
...
_Tenth header_
Tenth paragraph and more text*
Messagefile
a)
product.info = "<many paragraphs of text including headers>"
or splitting one page into html elements
b)
product.info.h1 = "<first header>"
product.info.p1 = "<first para>"
product.info.p2 = "<2nd para>"
For me both solutions doesn't sound right. In first having a vast value for a single key seems bad convention and in latter separating a single page into dozens of keys doesn't sound good either.
Big websites often follow the convention www.site.com/en-us/product/1 of having the language in the URL. So the question is, how do i do in this way and is doing in this way a better way at all? I could easily end up not just translating to dozen languages but doing also dozen times layout changes.
I could use global codesnippets using Messagefile for elements that have a little text and doesn't change often e.g. navigation /view/global/header/somenavbar.scala.html but then i end up only having a complex folder structure.
Another way, a best practise, in Play 2 for internalization than messagefile?
Take a look to the Joscha Feth's solution in play_authenticate Java sample.
There are templates for emails in 3 languages for email confirmation, password reseting etc.
Template for each 'type' of email && each language is kept in single file ie:
_password_reset_en.scala.html
_password_reset_de.scala.html
_password_reset_pl.scala.html
_verify_email_en... etc
And for each 'type' there is an 'parent' template, which contains a condition (common Scala's match check the Tags section of template doc) which returns rendered view depending on detected language:
password_reset.scala.html
Finally, yes, at the beginning I also thought that some kind of madness, but believe me, that technique can be useful. There's field for further improvements I think. Maybe it would be better to move the language conditioning to the controller, hm I think that depends on many factors and it will be great if you'll find a time to investigate this topic.