I have seen strange comments in code. For example what is the meaning or purpose of the following comments found here:
//<co id="callout-intro-countstream-index-1" />
//<co id="callout-intro-countstream-index-2" />
//<co id="callout-intro-countstream-index-3" />
//<co id="callout-intro-countstream-index-4" />
The code is for the Manning Book Node.js in Practice. The comments indicate the callouts targets (i.e. numbered annotations) that the author references in the text while explaining the code listing.
It is DocBook formatting: http://www.docbook.org/tdg/en/html/co.html
Related
How to insert a cross-reference in a reST/Sphinx page to either a sub-header or anchor in another page in the same documentation set?
The expression "reST/Sphinx" makes the scope of the question unclear. Is it about reStructuredText in general and Sphinx, or only about reStructuredText as used in Sphinx (and not reStructuredText in general)? I'm going to cover both since people using RST are likely to run into both cases at some point:
Sphinx
Besides the domain-specific directives that can be used to link to various entities like classes (:class:) there's the general :ref: directive, documented here. They give this example:
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.
Although the general hyperlinking mechanism offered by RST does work in Sphinx, the documentation recommends against using it when using Sphinx:
Using ref is advised over standard reStructuredText links to sections (like Section title_) because it works across files, when section headings are changed, and for all builders that support cross-references.
RST, in General
The tools that convert RST files to HTML do not necessarily have a notion of collection. This is the case for instance if you rely on github to convert RST files to HTML or if you use a command line tool like rst2html. Unfortunately, the various methods to use to get the desired result vary depending on which tool you are using. For instance, if you use rst2html and you want file A.rst to link to a section named "Section" in file other.rst and you want the final HTML to work in a browser, then A.rst would contain:
`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.
You have to link to the final HTML file and you have to know what the id given to the section will be. If you want to do the same for a file served through github:
`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.
Here too you need to know the id given to the section. However, you link to the RST file because it is only upon accessing the RST file that the HTML is created. (At the time of writing this answer, accessing the HTML directly is not allowed.)
A complete example is available here.
New, better answer for 2016!
The autosection extension lets you do this easily.
=============
Some Document
=============
Internal Headline
=================
then, later...
===============
Some Other Doc
===============
A link- :ref:`Internal Headline`
This extension is built-in, so all you need is to edit conf.py
extensions = [
.
. other
. extensions
. already
. listed
.
'sphinx.ext.autosectionlabel',
]
The only thing you have to be careful of is that now you can't duplicate internal headlines across the doc collection. (Worth it.)
Example:
Hey, read the :ref:`Installation:Homebrew` section.
where Homebrew is a section inside a different document named Installation.rst.
This uses the autosection feature, so will need to edit config.py with the following:
extensions = [
'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
In Sphinx 3.0.3 the only solution that worked for me is :any: (see https://www.sphinx-doc.org/en/1.5/markup/inline.html#cross-referencing-anything).
Suppose, one document has such a section:
.. _my-section:
My Section
----------
Lorem ipsum blablabla
Then another document can have the following fragment to create a link:
See :any:`my-section` for the details
I was struggling to make this work and i found out that the actual notation is :ref:'{dir-path}/Installation:Homebrew' where {dir-path} is the relative path to Installation.rst from where config.py exists
Adding description of behavior that was confusing to me.
Section titles must be referenced with the file name (overview here) in front of it:
overview.rst:
************
API Overview
************
index.rst:
:ref:`overview:API Overview`
However, when referencing links, the file name (constants here) must not be there:
constants.rst:
.. _section-constants:
*******************
Enums and Constants
*******************
api.rst:
:ref:`section-constants`
Also, for this to work, one must enable extension 'autosectionlabel':
conf.py:
extensions = [
...
"sphinx.ext.autosectionlabel"
]
I'm willing to use microdata/microformat/etc. for the part of my website which is an online dictionary. Basically I just want to tag word and definition to help search engines to grab the most important data in every page belonging to the dictionary, and maybe have Google use them as "rich snippets" in results page.
Main problem is it's hard to find dedicated vocabulary for words and definitions (no problem for recipes, movies and hotels though) and I'm not sure if I have to use the "http://schema.org/Article" tree for my lexicographic work. (To my mind, it makes sense to tag something when it's specific enough).
I have found something interesting at Yandex, for words and encyclopedia, I want to ask what to do with. See there :
https://yandex.ru/support/webmaster/microdata/what-is-microdata.xml?lang=en
https://yandex.com/support/webmaster/microdata/term-definition-markup.xml
It looks like it is very close to my request. But I'm sorry I dont know what is Yandex... will it work with Google ?
I'm asking here if that page, from Yandex, is a working model, is still on use, what are the pros and cons ? Will Google be able to use the specific vocabulary from Yandex and understand my Yandex-tagged data ? is it worth using that vocabulary for an online dictionary, or is something else I have missed of better use ?
(http://webmaster.yandex.ru/vocabularies/term-def.xml, which should be the vocabulary url, gives me a 404).
One more question, please : am I allowed to write (duplicate) the most important data in the header, something like (I believe I am, because Google microdata testing tool prooves to be able to extract the data from that code) :
<html itemscope itemtype="http://webmaster.yandex.ru/vocabularies/term-def.xml">
<meta itemprop="term" content="My term" />
<meta itemprop="definition" content="My definition" />
Just to mention I was interested, though not happy with these close discussions :
https://webmasters.stackexchange.com/questions/55073/what-meta-tag-or-structured-data-should-i-use-for-a-dictionary-web-application
schema.org and an online dictionary
Yandex is Russia's version of Google, and typically they both recognize and honor each other's search engine result implementations.
These articles you are referencing are incredibly outdated; I recommend you seeking out fresher sources, preferably where the term being defined uses the proper HTML element.
Here's the Yandex URL that is 404ing, the Wayback Machine is your friend!
Back to fresher documentation/resources, in this case the correct element as of 2016-10-05 is the <dfn> element. I know you want added semantics, but semantics is the proper place to start, and I'd follow that up by marking the entire dictionary up within a Definition List element, and placing the definition wrapped in the definition element into the <dt>, and the definition's of the term in the corresponding <dd>s.
I wouldn't waste time trying to find the perfect ontology here; implement [rel="tag" Microformat on all of the definitions], you can always come back and add a more desired one.
I've written a blog post about this, but a much more valuable resource is HTML5 Doctor's Glossary impementation, More importantly, view source - view-source:http://html5doctor.com/element-index/ (why stackoverflow doesn't recognize 'view-source' schema is beyond me)
More References/Resources:
Microformats Definition Examples has some very interesting ideas/code snippets
Utilizing the Underused by Semantically Awesome Definition List - Written Prior to HTML5's Redefinition of <dl> but Relevant
I've been asking Goodle and Stackoverflow variation of this query:
Syntax highlighting of mediawiki syntax
almost without exception I'm getting hits referring me to the Mediawiki Extension:SyntaxHighlight page. Unfortunately that is the question in this case, not the answer.
I did find a hit on MoinMoin ironically that wiki has MediaWiki syntax highlighting.
What I'd like to be able to do is to use syntaxhighlight around some mediawiki page mark-up to demonstrate how different pages or sections can be set-up. For now I'm using the <syntaxhighlight lang="text" ... >.
I'd like either a suitable "wiki"-highlight option or an workable alternative that will highlight some wiki markup. Ideally it would be fantastic to say:
<syntaxhighlight lang="mediawiki" > ... </syntaxhighlight>
I am surprised that this hasn't been asked before though.
edit 2016-05-09:
As a work around I have settled on the following for the time being. It isn't as pretty as having the final tag inside the syntaxhighlight but it gets the job done:
== xml ==
<syntaxhighlight lang="text" highlight="1,11">
:<syntaxhighlight highlight="6" lang="xml">
<tomcat-users ...>
<role rolename="manager-gui"/>
<role rolename="manager-script"/>
<user username="admin" password="****" roles="manager-gui,manager-script"/>
</syntaxhighlight>
<code><nowiki></syntaxhighlight></nowiki></code>
Which shows the closing </syntaxhighlight> tag outside the main box.
In the core, Extension:SyntaxHighlight uses Pygments, and it is extensible to make your own "syntax highlighting" or find a big set of other languages, take a look maybe you can find something useful, but I'm not sure that it will be something out of the box.
In HTML, I was always taught to close self-closing with a "/>". For example "<br />", "<input type='button' value='myButton' />", etc.
In Coldfusion, though, it seems to be standard to just never close these tags. I'm constantly seeing code like:
<cfset myVariable = someValue>
<cfset myOtherVariable = someOtherValue>
etc.
Is this bad code, or is it commonly accepted? I've seen it almost anywhere that I've seen coldfusion code. Is there any benefit to closing these tags, or is it fine to leave it as it is?
Because there's no official coding standard for CFML, it's up to you whether to use these. Same as using uppercase/lowercase tags.
Personally I love to have my code beautiful and readable, so I'm always using this syntax for single tags.
But there is at least one techincal difference: custom tags. Let me show this by example.
Consider following custom tag:
<cfif thisTag.ExecutionMode EQ "start">
started<br/>
</cfif>
running<br/>
<cfif thisTag.ExecutionMode EQ "end">
ended<br/>
</cfif>
Now these two types of invokation:
<p><cf_demo></p>
<cf_demo>
<p><cf_demo /></p>
<cf_demo />
And here's the output:
<cf_demo>
started
running
<cf_demo />
started
running
running
ended
Second syntax is equivalent of <cf_demo></cf_demo>.
Possibly there are more differences, but I can't remember any at this moment... :)
It doesnt matter, it is also not necessary in html unless it is xhtml.
I agree with the last comment.
I hate those single tag closes.
It's pointless and not a coding standard for CFML.
It started appearing when xml became popular due to it's strict tag syntax and people assuming it was correct for CFML. CFML isn't HTML. Treating it as such is really in itself lazy coding. I also think it looks more beauiful without the unnecessary closing /> :)
but that's me for you.
I also dislike {} spread on to new lines for each bracket. I guess it's just personal preference.
I never used to use the /> until i started using Dreamweaver CC and the auto close only works if you close the tags somehow
PHP CodeSniffer is a very good tool to help us check our PHP source code. But the report from CodeSniffer is not easy to read.
I found that CodeSniffer can output 'Checkstyle' xml report. Is that any way to Visualize PHP code with Checkstyle xml report, so that every developer can read code and report in one page?
In fact, I found a tool named phpUnderControl, which looks like a very good Continuous Integration tool and something inside it could cover my requirement. But I have no plan to change my Continuous Integration tool (I'm using Apache Continuum).
So if anyone can tell me a simple tool or plug-in, that would be the best.
Thanks.
This is really more of a comment/question, but SO thinks it is too long so I'll phrase it as an answer:
Assuming you want to take output like this:
$ phpcs --report=checkstyle /path/to/code
<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="1.0.0">
<file name="/path/to/code/myfile.php">
<error line="2" column="1" severity="error" message="Missing file doc comment" source="PEAR.Commenting.FileComment"/>
<error line="20" column="43" severity="error" message="PHP keywords must be lowercase; expected "false" but found "FALSE"" source="Generic.PHP.LowerCaseConstant"/>
<error line="47" column="1" severity="error" message="Line not indented correctly; expected 4 spaces but found 1" source="PEAR.WhiteSpace.ScopeIndent"/>
<error line="47" column="20" severity="warning" message="Equals sign not aligned with surrounding assignments" source="Generic.Formatting.MultipleStatementAlignment"/>
<error line="51" column="4" severity="error" message="Missing function doc comment" source="PEAR.Commenting.FunctionComment"/>
</file>
</checkstyle>
and render a version of the original source code with the indicated sections highlighted somehow, then I think you're going to have "to roll your own".
You'd have to write a script which takes the path to a source file in your code repository as an input parameter (e.g. path/to/code) and a chunk of "checkstyle" XML as input (via STDIN), and renders the contents of the file (to STDOUT) as HTML markup.
The body of the file inside should be in a PRE element (to preserve formatting) and each specified line + column with an HREF link to an error/warning "list element" would be at the bottom of the HTML page (I'm not sure what kind of addition color/highlighting can work inside a PRE element).
This is a good idea - I would like to have such a script/tool/utility myself! If I ever get around to writing one I promise to publish it on Github and add a link to it here.
And if you ever find/write one, PLEASE answer your own question, OK?