I would like to insert a ASCII art table (as below) in the documentation.
The Markdown feature of doxygen comes in the way and messes it all up.
I've tried to the HTML table and they are fine but the source document becomes unreadable then.
Can I somehow get doxygen not to process a section but still include it in the output file?
Similar to here where 4 blanks allow to to inserted already formatted text in fixed width font.
|-------------|-------------------------|---------------|
|AUTO_NEW_OFF | Entry action | LED_FLASH |
| | | SEQ_OFF |
|-------------|-------------------------|---------------|
| | eXit action | |
|-------------|-------------------------|---------------|
| | | |
|-------------|-------------------------|---------------|
| OFF | SEQ complete | |
|-------------|-------------------------|---------------|
I think I can answer this myself already.
The Fenced Code Blocks ( 3 x ~) feature seems to work ok
~~~
|-------------|-------------------------|---------------|
| MAN_NEW_OFF | Entry action | LED_FLASH |
| | | SEQ_OFF |
|-------------|-------------------------|---------------|
~~~
An improvement on fenced code would be to surround the table with the doxygen commands #verbatim and #endverbatim.
If you use a "code" style, be that markdown's ~~~ or doxygen's #code, there's a chance that current or future versions of Doxygen will start trying to colour it in syntactically.
Related
We are using Serenity with Jbehave for out automation stories, and we have recently upgraded our version to Serenity(2.2.1) and jbejave(1.46.0). Jbehave-core updated from 4.1.3 to 4.4. After the update i am facing an issue with examples table. it is forcing to use delimiter for the step table provided which is taken from story Examples.
This worked previously and got expected values into table
Scenario: Verify scenario
Meta:
Given modal should contains the next content:
{transformer=FROM_LANDSCAPE}
| modalTitle | expectedTitle1 |
| modalFooterTitle | expectedFooterTitle |
Examples:
{transformer=FROM_LANDSCAPE}
| expectedTitle1 | this is first expected title |
| expectedFooterTitle | This is expected footer text |
Now i have to use delimiter to get my expected content into table as below
Given product modal should contains the next content:
{transformer=FROM_LANDSCAPE}
| modalTitle | <expectedTitle1> |
| modalFooterTitle | <expectedFooterTitle> |
Examples:
{transformer=FROM_LANDSCAPE}
| expectedTitle1 | this is first expected title |
| expectedFooterTitle | This is expected footer text |
Also tried with configuration steps like ParameterControls().useDelimiterNamedParameters(false) but didn't worked. We have already implemented thousands of stories and it is hard to replace storied with delimiters. is there any work around to solve my problem?
I'm working on web app which enables the user to search within a source repository.
The program parses the diffs.
I can't find a way to inject all parts of the diff into the Postgres' fulltext vector.
Example:
select alias, description, token from ts_debug('Link to Yahoo! web site');
+-----------+-----------------+----------------------------+
| alias | description | token |
+-----------+-----------------+----------------------------+
| asciiword | Word, all ASCII | Link |
| blank | Space symbols | |
| asciiword | Word, all ASCII | to |
| blank | Space symbols | |
| tag | XML tag | <a href="//www.yahoo.com"> |
| asciiword | Word, all ASCII | Yahoo |
| blank | Space symbols | ! |
| tag | XML tag | </a> |
| blank | Space symbols | |
| asciiword | Word, all ASCII | web |
| blank | Space symbols | |
| asciiword | Word, all ASCII | site |
+-----------+-----------------+----------------------------+
It seems to be parsed ok. But if I turn it into a document vector the XML tag won't be included.
select to_tsvector('simple', 'Link to Yahoo! web site') to_tsvector;
+--------------------------------------------+
| to_tsvector |
+--------------------------------------------+
| 'link':1 'site':5 'to':2 'web':4 'yahoo':3 |
+--------------------------------------------+
I guess it has something to do with the configuration?
Any ideas?
The parser parses out tags, but the default configuration 'simple' ignores them (as can be seen in psql by running \dF+ simple, tokens not listed are ignored).
You can tell it not to ignore them:
alter text search configuration simple add mapping for tag with simple;
But you would probably be better off copying the configuration and then modifying the copy.
You might also need a custom dictionary to process the tags, since the 'simple' dictionary is unlikely to do what you want.
select to_tsvector('simple', 'Link to Yahoo! web site') to_tsvector;
to_tsvector
------------------------------------------------------------------------------------
'</a>':5 '<a href="//www.yahoo.com">':3 'link':1 'site':7 'to':2 'web':6 'yahoo':4
When I insert a table using M-x table-insert
I get the following table:
+-----+-----+-----+
| | | |
+-----+-----+-----+
| | | |
+-----+-----+-----+
| | | |
+-----+-----+-----+
But When I add content the | become disaligned like this
+-----+-----+-----+
| content | | |
+-----+-----+-----+
| | | |
+-----+-----+-----+
| | | |
+-----+-----+-----+
How do you realign the column?
When I press enter it just creates that:
+-----+-----+-----+
| contecnt | | |
| | | |
+-----+-----+-----+
| | | |
+-----+-----+-----+
| | | |
+-----+-----+-----+
You enter the corresponding cell and start editing the text with C-c' it opens the edit mode and automatically wraps the text accordingly. Once done type C-c' again and you're back in the nicely formated table.
The table should expand as needed for words longer than the width of the column, and the entire column should widen when this happens. Multiple words will wrap appropriately when the width is reached if there is space to break the line. Remember to use tab to move from cell to cell in the table.
Column width can be changed manually with M-x table-widen-cell and M-x table-narrow-cell.
Sometimes Emacs gets confused for some reason, and something like what you describe happens. One way to fix it is to exit table mode with M-x table-unrecognize-table, manually edit the table, then do M-x table-recognize-table. It's not ideal, but sometimes is easiest.
Yes, org-mode table and table-mode table functionality are interfering with one another and preventing the table from realigning properly. I'm not sure how to fix that, but you mentioned in a comment that you are using table-mode specifically because you want multi-lined cells in the table.
I suggest that instead you use an org table (with M-x org-table-create) and then you can split long lines over multiple lines within the same cell by calling M-x org-table-wrap-region at the point where you want the split.
Just press TAB within the table and it will autoalign.
How can you add tables with multi-row cells to markdown in Microsoft VSTS?
I have previously used asciidoc for readme files on github as it is both richer and less ambiguous. The company now has projects on VSTS which does not support asciidoc so I need to use markdown instead.
However, it is unclear what flavour of markdown is actually supported
This page says that github flavoured markdown can be used
https://learn.microsoft.com/en-us/vsts/collaborate/markdown-guidance
I found another page saying they use commonmark via the markdown-it library.
Q: Does VS Code support GitHub Flavored Markdown?
A: No, VS Code targets the CommonMark Markdown specification using the
markdown-it library. GitHub is moving toward the CommonMark
specification which you can read about in this update.
I've been using a combination of asciidoctor and pandoc to convert files but nothing gets it quite right.
(Asciidoctor converts to docbook which pandoc can then parse)
asciidoctor -b docbook -v -o "$OUTPUT".xml "$INPUT" &&
pandoc -f docbook -t markdown_github -i "$OUTPUT".xml -o "$OUTPUT"
I have to re-add the title manually.
My current stumbling block is multi-row cells.
Github supports grid tables,
see Newline in markdown table?:
+---------------+---------------+--------------------+
| Fruit | Price | Advantages |
+===============+===============+====================+
| Bananas | first line\ | first line\ |
| | next line | next line |
+---------------+---------------+--------------------+
| Bananas | first line\ | first line\ |
| | next line | next line |
+---------------+---------------+--------------------+
But neither this nor embedded html seem to work in VSTS.
I would be happy to use html readmes instead if that was permitted.
Update 17-Nov-2017:
I found the link to markdown-it and added it above. I've raised an issue there for clarification (or enhancement). Its unclear which version VSTS actually uses under the hood.
I would like to ask the question of Microsoft themselves but their ask a question link goes straight to stack overflow.
The markdown-it library does support the usage suggested by #Waylan:
| Fruit | Price | Advantages |
| ------------- | ----------------------- | ----------------------- |
| Bananas | first line<br>next line | first line<br>next line |
| Bananas | first line<br>next line | first line<br>next line |
See https://github.com/markdown-it/markdown-it/issues/406.
The issue is most likely Microsoft disabling html.
A solution thus waits on a reply to #starian's suggestion: https://visualstudio.uservoice.com/forums/330519-visual-studio-team-services/suggestions/32312290-multi-line-in-the-cell-of-a-table-in-markdown-in-v
In short, each row must be on one line and should use <br> to indicate a line break. Like this:
| Fruit | Price | Advantages |
| ------------- | ----------------------- | ----------------------- |
| Bananas | first line<br>next line | first line<br>next line |
| Bananas | first line<br>next line | first line<br>next line |
Below is an explanation of each tool with an analysis of that tool's documentation:
GitHub
CommonMark is a Markdown variant with a strict spec. GitHub-Flavored Markdown (GFM) is an extension of CommonMark (which adds features to CommonMark such as tables), with its own spec. Therefore, to say that an implementation supports GFM is to say that it supports CommonMark with extensions. Note that GitHub adopted the current spec on March 14, 2017, so any information older that that may not be relevant for the current implementation.
Whether VSTS actually uses a CommonMark/GFM implementation or a close approximation is unclear from the documentation. However, as the documentation clearly states that "GitHub-flavored extensions" are supported, that would indicate to me that the GFM Spec would be a good reference. Regardless, the GFM Spec is the controlling spec for any Markdown rendered on github.com.
The Tables section of the GFM Spec plainly states:
Block-level elements cannot be inserted in a table.
And gives this simple example:
| foo | bar |
| --- | --- |
| baz | bim |
While the spec does not specifically mention multiple line cells, there are no examples with any cells that contain multiple lines. It is my understanding that that is not supported by GFM. Therefore, the only way to include line breaks in GFM Table cells is with the <br> tag, which is not a block-level element.
Pandoc
Pandoc supports multiple different styles of table syntax. If you are passing your Markdown to both Pandoc and GFM, then you need to use Pandoc's table style which most closely matches GFM's style. For example, GFM Tables do not include support for + at the corners. That syntax is specific to Pandoc's Grid Tables. Fortunately, Pandoc's documentation tells us which style most closely matches GFM.
Pandoc has support for various "Markdown Variants", one of which is gfm. The docs have this to stay about that variant:
We also support gfm (GitHub-Flavored Markdown) as a set of
extensions on commonmark:
: pipe_tables, raw_html, fenced_code_blocks, auto_identifiers,
ascii_identifiers, backtick_code_blocks, autolink_bare_uris,
intraword_underscores, strikeout, hard_line_breaks, emoji,
shortcut_reference_links, angle_brackets_escapable.
Note that the gfm variant of Pandoc uses Pipe Tables. It is also noteworthy that the markdown_github variant of Pandoc is deprecated since GitHub adopted Commonmark. But even the markdown_github variant uses Pipe Tables.
Pandocs' documentation for Pipe Tables states (emphasis added):
The cells of pipe tables cannot contain block elements like paragraphs and lists, and cannot span multiple lines.
And gives this example:
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1 | 1 | 1 |
That is clearly the same as GFM tables and does not include any support for block level elements or multi-line cells.
VSTS
The VSTS Documentation for Tables closely matches GFM and Pandoc Pipe Tables with this example:
| Heading 1 | Heading 2 | Heading 3 |
|-----------|:---------:|----------:|
| Cell A1 | Cell A2 | Cell A3 |
| Cell B1 | Cell B2 | Cell B3 |
While the the VSTS Documentation makes no specific mention of block-level elements or multiple lines, is seems safe to assume that it is in fact the same style.
We can make that assumption because in all three instances (VSTS, GFM and Pandoc Pipe Tables), the syntax does not provide a divider between individual rows of the table (compare with Pandoc Grid Tables, which supports row dividers). While there is a divider between the header and data rows, with no divider between individual data rows, there is no way to indicate how many lines of text belong to each row. Therefore, each row can only be represented by one line of text.
Conclusion
Given the above, to be parsed properly by VSTS, GFM and Pandoc (gfm variant), your table should be formatted like this:
| Fruit | Price | Advantages |
| ------------- | ----------------------- | ----------------------- |
| Bananas | first line<br>next line | first line<br>next line |
| Bananas | first line<br>next line | first line<br>next line |
And when using Pandoc, be sure to use the gfm format (pandoc -f gfm ...).
It is not supported in markdown of VSTS, I submit a user voice here: multi-line in the cell of a table in markdown in VSTS, you can vote and follow it.
I have been developing an application with the following layout (greatly simplified):
+----------------------------------+
| +----------------+ |
| Main | | Info |
| | Interactive | |
| Actions | | And |
| | Graph | |
| Go | | Forms |
| | (Resizable) | |
| Here | | |
| +----------------+ |
+----------------------------------+
With a screen resolution of 1440x900. There are some minimum widths set for buttons etc to make them more beautiful (so for example the label inside has some distance from the button borders). Now if I resize the window to about 800x600, it becomes like this:
+----------------------+
| +----+ |
| Main | | Info |
| Actions | | And |
| | | |
| Go | | Forms |
| Here | | |
| +----+ |
+----------------------+
Which is not so beautiful. The reason the middle panel gets so small is that the labels on either sides cannot be shrunk.
The question is, how can I tell gtk to scale everything (e.g. images, fonts etc) inside a window?
If such a functionality doesn't exist, what choice do I have for making everything inside the window (or at least the font sizes) smaller or bigger, without having to manually change every widget?
Gtk doesn't allow you to "scale" anything automatically in a window. It would also be a bad idea, as you don't know how little the window will be (not only because of the screen resolution, but because of the user manually resizing the window).
I'd suggest you to redesign your layout. It's complicated to suggest a solution without a real screenshot, but maybe the Main Actions could be replaced in the top part of the window.
Use a toolbar with your main actions, and put other actions in a menu bar. This will give more space to the interactive graph. Info and forms, if not required at every moment, may be in a tabbed view, or in a popup. Hard to tell more without a screenshot.