Ho can I include inside an asciidoc code fence? Here is a sample:
[source,js]
----
function doit() {
*var thing;* // local variable
}
----
The idea is that I would like to highlight certain parts of the code block for teaching purposes.
The above sample doesn’t work.
I have read about using something like [subs="macro"], but (a) I can’t get it working in combination with a code fence, and (b) the documentation is a little unclear about the actual details.
Thanks
BTW I am aware of a similar question AsciiDoc add bold text inside a listing block, but there is no reference to code fences. I have tried the solutions, but the don’t work in this context.
According to AsciiDocs Documentation, below code
[source,java,subs="verbatim,quotes"]
----
System.out.println("Hello *bold* text").
----
will be displayed as
System.out.println("Hello bold text").
So, you need this -
[source,js,subs="verbatim,quotes"]
----
function doit() {
*_var thing;_* // local variable
}
----
It will be displayed as
verbatim and quotes subs are helpful.
NOTE:
One thing we need to keep in mind that the code block is already highlighting syntax. If you want different formatting, better not to use code block.
In my opinion the philosophy of Asciidoctor for those use case is to use callouts.
[source,js]
----
function doit() {
var thing; // <1>
}
----
<1> local variable
The second thing you should consider is to extract your code from a real, controled, unit-tested file. You define some markers in this code file and add an include directive in your adoc file.
Check slides 15-21 in this presentation:
Writing documentation with Asciidoctor
Related
Basically I want to write one piece of text which qualifies both as a working code and MarkDown (preferably GitHub flavor) for documentation. The language I'm using has C form commenting \\ for rest-of-line and /* ... */ for multi line comments. So far what I can do is:
/* --> start with multi line comments
here some markdown text
# heading
* list
end markdown section with
<!--- */ // -->
or
[//]: # (end of comment block --> */ // <-- inline comment)
_-_-indented code
_-_-_-_-more indented code
The issues are:
the first /* still showing in the documentation
I can't use the proper multiline code block ``` ... ```. I have to indent the code parts once more than what is required. Also the syntax highlighting doen't work in this format AFIK.
I would appreciate if you could help me know first how to solve above issues. and Secondly if there is any better way to do this?
I think I have a proper solution now with colapsible / foldable code section:
/*
This is the markdown **text**
used for documentation
<details>
<summary>Click to see the source code</summary>
``` scilab
*/
This is the
actual code
which will
be executed
/*
```
</details>
<!--- */ // -->
which will be rendered as:
/*
This is the markdown text
used for documentation
*/
This is the
actual code
which will
be executed
/*
The collapsible section makes sure that the documentation is clean and readable. you may see the final result here on GitHub. I used the code from here. Now there are a bunch of /*s and */s which would be nice to get ride of. Next step would be to modularize the MarkDown document into different files as I have asked here.
P.S. Implementation of the same idea using AsciiDoc here.
class torch.FloatStorage[source]
byte()
Casts this storage to byte type
char()
Casts this storage to char type
Im trying to get some documentation done, i have managed to to get the format like the one shown above, But im not sure how to give that link of source code which is at the end of that function!
The link takes the person to the file which contains the code,But im not sure how to do it,
This is achieved thanks to one of the builtin sphinx extension.
The one you are looking for in spinx.ext.viewcode. To enable it, add the string 'sphinx.ext.viewcode' to the list extensions in your conf.py file.
In summary, you should see something like that in conf.py
extensions = [
# other extensions that you might already use
# ...
'sphinx.ext.viewcode',
]
I'd recommend looking at the linkcode extension too. Allows you to build a full HTTP link to the code on GitHub or such like. This is sometimes a better option that including the code within the documentation itself. (E.g. may have stronger permission on it than the docs themselves.)
You write a little helper function in your conf.py file, and it does the rest.
What I really like about linkcode is that it creates links for enums, enum values, and data elements, which I could not get to be linked with viewcode.
I extended the link building code to use #:~:text= to cause the linked-to page to scroll to the text. Not perfect, as it will only scroll to the first instance, which may not always be correct, but likely 80~90% of the time it will be.
from urllib.parse import quote
def linkcode_resolve(domain, info):
# print(f"domain={domain}, info={info}")
if domain != 'py':
return None
if not info['module']:
return None
filename = quote(info['module'].replace('.', '/'))
if not filename.startswith("tests"):
filename = "src/" + filename
if "fullname" in info:
anchor = info["fullname"]
anchor = "#:~:text=" + quote(anchor.split(".")[-1])
else:
anchor = ""
# github
result = "https://<github>/<user>/<repo>/blob/master/%s.py%s" % (filename, anchor)
# print(result)
return result
In Visual Studio you can minimize huge chunks of code using regions; they essentially just surround the code and minimize it in the window.
Does Sublime have a feature similar to this?
By default, you can select some code the go to Edit > Code Folding > Fold. There are tons of plugins that leverage the code-folding api for more options.
There's a request on the official site to "ask for features" here.
But apparently:
FYI, Jon has stated that this is not possible in the current
implementation of the editor control. Looks like we're waiting till V3
guys.
Jon being the programmer behind Sublime Text 2.
There might be a way to fake it by creating a plugin that looks for markers and removes the code region in between the markers, but it probably wouldn't look good. With the current API, it's probably your best bet!
By the way, there is some code folding in Sublime Text, if you hover your mouse next to the line number, you will see some arrows appearing when you can fold / unfold.
I ended up using custom comment tags, indented one level less than the code I want to fold. It doesn't look best, though it serves its purpose.
class Foobar {
// ...some code
// <fold
function foo() {
}
function bar() {
}
// </fold
// more code...
}
This (at the moment) folds to:
class Foobar {
// ...some code
// <fold[...]
// </fold
// more code...
}
Having a native ST2 support for this would be nice.
This looks what you are looking for. You can define tags for #region and #endregion for each language, or a generic tag for all of them.
If you are obsessed with intendation, this solution may make you uncomfortable but here it is, once upon a time while I had been writing a semi-complex jQuery plugin I've had constants, variables, private and public functions sections and foldings like so;
;(function($, undefined, window) {...
/* Consts */
var FOO = "BAR";
/* Variables */
var m_Foo = "bar";
/* Functions */
/* Public Functions */
function foo() {...}
function bar() {...}
/* Private Functions */
function _foo() {...}
function _bar() {...}
})(jQuery, window);
As you can see it is all about intendation. Sections can be folded; Consts, Variables, Functions. And also inside Functions section, Public Functions and Private Functions are both can be folded.
You can also use one line comment (//) to name your fold. So the idea underneath that is simple; ST2 thinks that the more intended lines belongs to first less-intended comment above them, like C/C++ compilers how handle brackets as own unique code blocks.
To fold the code select the code and press
ctrl + shift + [
To unfold the code put the cursor there and press
ctrl + shift + ]
I think that like myself, the OP has come to appreciate a little-known feature in VS called regions that many equate to code-folding, but is FAR more powerful and above, Dio Phung provided the answer that I wanted, and I suspect the OP wanted, but he didn't share as an answer so here it is.
The difference between "code-folding" as it's provided in Sublime Text is that it's based on code/compiler syntax while "regions" and what this plugin does, allow you infinitely more freedom, though it's a freedom that's more or less dependant on the code you're working with to begin with (deeply nested, or properly modularized).
If you are on Sublime Text 3, here is a plugin that can do it :
github.com/jamalsenouci/sublimetext-syntaxfold – Dio Phung
In languages which support 3 types of comments (e.g. PHP) I use the hashtag comment for regions, as shown in the other answers. It's also good for keeping track of what's being done
# default options
$a = 3;
$b = 'bob';
$old_code = 1;
# bugfix #130
$result = magic_function($data);
fix_stuff($result);
$old_code = $result;
Otherwise use triple slash ///, or //# etc.
In sublime text, it works like this, it shades the lines you want to collapse and presses (Control + Shift +?)
I have the most recent version of sublimetext.
Let me start with I'm not a programmer by trade, but I'm learning the best I can. I'm trying to build a template to take the result of one FreeMarker interpolation result and use that as a variable for another. I hope I'm using the terms correctly.
For example, I want the result of (entity.customer.organization.name) to be used in:
${blurb["organizationXXXAttire"]!}
Where XXX is the result of (entity.customer.organization.name)
If it was just a blurb with out a variable company name it would look like:
${blurb["organizationCompanyAttire"]!}
I thought the following would work but it did not:
<#assign organization = (entity.customer.organization.name)>
${blurb["organization<#organization?interpret>Attire"]!}
Thanks in advance for any suggestions.
It's simply ${blurb["organization${entity.customer.organization.name}Attire"]!}.
?interpret is only needed if you have a string that contains a piece of template. Besides you can't call directives (<#...>, <#...>) inside an expression.
In VS 2008, there are XML code snippets that seem to be pretty awesome :) However, it seems that the snippets we created do not indent properly. For example if we have the following code:
{
...
{
...
{
InsertSnippet here.
We get something like:
{
...
{
...
{
FirstLineofSnippet
SecondLineOfSnippet
ThirdLineOfSnippet
Is there any way to make it so that all lines keep the same indentation?
This usually indicates that the code you are inserting is semantically incorrect - at the time of insert, not when you filled in the snippet values.
To prevent this you can use default values in your snippet to make the snipped syntactivaly correct. E.g. to declare an argument list for a function:
<Literal Editable="true">
<ID>methodArguments</ID>
<ToolTip>methodArguments</ToolTip>
<Default>params object[] args</Default>
<Function>
</Function>
</Literal>
The <Default> Element provides the declaration. So using this in a snippet declaring a funciton will lead to this:
public void FunctionName(params object[] args) { }
And it then lets you replace params object[] args with whatever argument declarations you need.
paste the first line without indentation, then select the block and tab until you get the whole block to the indentation you want. AFAIK what you see is the standard behavior and it happens because the location you paste from wasn't indented as far as you wanted.
My unit test snippet appears to be indenting correctly. It may be due to the fact that the code is wrapped in a CDATA block. VisualStudio also tends to auto-format the block as soon as it is added to the code. Does your snippet have as many open braces as closing ones? If the two match up, and the snippet is inserted in a valid/compilable location, it should auto-format.
It seems that Visual Studio does an auto-format on the inserted lines. My snippet wasn't correctly formatted (i.e. indented) either, neither by snippet insertion, nor by manual format (Ctrl-K-F). It contained "delegate{...}", maybe the formatter cannot handle this.
Try swithing from Insert spaces to Keep tabs in Tools > Options > TextEditor > C# > Tabs, it worked for me.