I'm build RST files for my company's documentation. One irritating thing is that enumerated lists don't seem to have any consistency in terms of line spacing.
Is there a simple way to solve this?
Robert
It's a well known problem of docutils, the library on which Sphinx is built.
From Sphinx issue tracker on GitHub:
tk0miya wrote:
In my short investigation:
The behavior comes from docutils (base library of Sphinx).
In docutils.writers.html4css1.HTMLTranslator, docutils generates <p> tag if list includes any items excepting paragraphs and nested lists.
To fix this, set self.compact_simple in visit_list_item instead of visit_bullet_list and visit_enumerated_list.
But we have to know why docutils check whole of list.
Source: Spinx-Doc/Sphinx #2258 - Nested field lists inside list items cause unwanted space in HTML output
See related issues:
https://github.com/rtfd/sphinx_rtd_theme/issues/119
I'm unsure how to apply Paebbels answer, however I was able to get rid of the <p> tags by changing to the html4 writer by adding this line to my conf.py.
html4_writer = true
This obviously changes it to the html4 writer, so you'll need to determine whether this is acceptable or not.
Related
What is the value in adding YAML atop an Azure DevOps Wiki page's markdown, as supported by its markdown syntax: Syntax guidance for Markdown usage in Wiki, YAML tags?
It seems to offer nothing more than an alternative syntax with which to specify tables. Perhaps more elaborate tables but they'll only render atop the page. What am I missing?
As the introduction in the document,
Any file that contains a YAML block in a Wiki is processed by a table with one head and one row.
So, I think the value of YAML tags in the Wiki markdown is to convert the abstract YAML statements into a visual table on the Wiki page to increase readability and quick understanding.
Especially for a complex YAML block that may contain multiple items or multiple sub-items, the YAML tags should be very helpful.
[UPDATE]
I find an issue ticket (MicrosoftDocs/azure-devops-docs#9976) reported by another user on the GitHub repository "MicrosoftDocs/azure-devops-docs". This issue has reported a similar question.
And in this issue ticket, you also can see #amitkumariiit has given an explanation:
Yaml tags are used for general search engine optimisation. Our plan was to add the basic support for it first and then ingest this in the azure devops wiki search for optimise search. However we could not prioritise the search side of work.
If you need more detailed explanation, you can follow this issue ticket and add your comments to it.
I am going to propose my own answer. It just occurred to me that this is likely intended to replace markdown, not to be used with markdown. That is to say, to support documentation written purely in YAML. That could make some sense, add value for some, and explain why it's ONLY supported atop the page. You use it instead of the markdown, not with the markdown.
The documentation just doesn't make it clear why/how you might want to use this feature.
I have several occurrences of same Anchor Tag string in one document - /sn1/. But when signing I can see only one generated field - near the first match. Documentation says that a sign tab is created in every place a match is found in a document. What am I doing wrong or should strings be unique?
Update: I have the document in Hebrew(RTL) language, probably it's somehow connected with the problem, as I tested another document, but this time in English, and had multiple fields at the place of anchor string instances with no problem.
Well, it was incorrect convertation via libreconv gem that prevented additional sign tabs from appearing. The problem was in initial convertation from .docx to .pdf using the above mentioned gem. I do not recommend it at least for RTL documents.
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.
Can I change the root of the treeview with a custom link instead of index.html?
Or at least add html before the treeview on the side-nav?
I think the answer is not with the vanilla Doxygen.
However, you may be able to get someway by using the '#page' documentation, which Doxygen will include before the API tree.
Doxygen also recognises '.dox' files as just containing Doxygen comment blocks - while not required for #page, these are useful where the supporting documentation is not linked to any particular source file. I've used these in the past to build the full SDK document, with background, examples, etc.
A variant is the '#mainpage', which comes first - otherwise #page entries are unordered. In the past I have modified Doxygen to order #pages by their internal name (as opposed to their title).
Could anyone suggest me a way to make long words (like serial numbers) to be wrapped? I tried some commercial software and there is no such issue. Is it a fop bug or probably there is a solution available?
I can't insert zero length space after each character of every word in document. This solution sounds insane for me.
You can specify the wrap-option attribute in your fo:block like so:
<fo:block wrap-option="wrap"> ... stuff </fo:block>
Here's the XSL-FO specification for this attribute:
XSL Definition:
Value: no-wrap | wrap | inherit
Initial: wrap
Applies to: fo:block, fo:inline, fo:page-number,
fo:page-number-citation
Inherited: yes
Percentages: N/A
Media: visual
Values have the following meanings:
no-wrap
No line-wrapping will be performed.
In the case when lines are longer than
the available width of the
content-rectangle, the overflow will
be treated in accordance with the
"overflow" property specified on the
reference-area.
wrap
Line-breaking will occur if the
line overflows the available block
width. No special markers or other
treatment will occur.
Specifies how line-wrapping
(line-breaking) of the content of the
formatting object is to be handled.
Implementations must support the
"no-wrap" value, as defined in this
Recommendation, when the value of
"linefeed-treatment" is "preserve".
You can also define the wrap-option attribute in an fo:table-cell
<fo:table-cell wrap-option="wrap"> ... </fo:table-cell>
and the fo:blocks within will inherit the property.
Zkoh's answer (wraping) will help you only if the text contains multiple words split by white spaces. In case of long words (as mensioned in question), hyphenation is way to go (as Daniel suggested).
There can be quite a few problems with hyphenation in FOP:
FOP is using hyphenation algorithms from TeX and because of some licencing issues, those algorithms (at least for some languages) are not part of standard FOP binary distribution (as stated here) and must be downloaded separately from OFFO web site. There are two kinds of hyphenation pattern files on the website. XML format (which needs to be compiled 1st to be used with FOP) and JAR file (already compiled). Be sure to download compiled version! Installation is straightforward and well documented - just drop the OFFO binary into FOP's lib folder and thats it...
Don't forget to specify language of your document and if needed, enable hyphenation on block level (its inherited so add it to the root element and you should be fine) - see FOP FAQ
Would hyphenation solve your problem? You should be able to enable hyphenation with a hyphenate="true" attribute. Placement of this attribute will depend on where you want to enable hyphenation.
Here's a link to FOP's hyphenation compliance: Apache FOP Compliance Page
Here's a link to the XSL spec: XSL Spec #hyphenate
If not, you may need to experiment with some keeps properties (like keep-together.within-line).
Use keep-together.within-column="always" instead of keep-together="always" of to keep long lines with in table cell.
The question is about serial numbers, not about dictionary words. Specifying hyphenate="true" is useful only when the hyphenation dictionary or hyphenation algorithm can successfully hyphenate the words in the text. Serial numbers would rarely generate sequences that can usefully be hyphenated as if they are words.
You can, of course, use XSLT to add zero-width spaces in text in table cells rather than doing it manually. StackOverflow likes duplicate questions (see https://stackoverflow.blog/2010/11/16/dr-strangedupe-or-how-i-learned-to-stop-worrying-and-love-duplication/), but, all the same, please see the answers in XSL-FO: Force Wrap on Table Entries.
For text overflow problem use keep-together="auto" attribute.
Text Overflow Issue
Fixed version after using keep-together="auto" attribute.