Prefixing the link with an ! suppresses the creation of a reference (e.g. :ref:`!no link` will be simply rendered as no link):
If you prefix the content with !, no reference/hyperlink will be created.
However, I can't think of any practical usage of this. Why should I first create a reference and then don't want to use it - it would be far easier to write plain text from the very beginning.
So - what is a typical use case of such a suppressed reference?
(Sphinx itself for instance doesn't use it in its docs.)
I can't think of any practical usage of this.
The use I can think of is before a build if you wanted to "turn of" hyperlink generation for one given cross-reference (that appears multiple times) how would you do it?
Well, the simplest way might be using some text editor's "find and replace", and arguably the least invasive way would be to add or remove a single character !. That way the length and structure of the cross-reference is kept in the source (and the title is still rendered in place). This could be convenient in several places, like a table where removing the whole cross-reference could misalign the source.
The most economical change possible would be turning this:
:ref:`a very long title <an.extremely.long.link.target>`
into this:
:ref:`!a very long title <an.extremely.long.link.target>`
The same could possibly be achieved programmatically using the Sphinx API, but a lot of Sphinx users are likely to prefer a text editing solution over a programmatic one.
One thing that constantly annoys me about VS is that when I do a Find or Find all, it looks in comments, strings, and other places. When I'm trying to find a particular bit of code, like and rent, it finds it all over. Is there a way to limit searches just to code?
Not sure if there is a specific setting to ignore comments, but you could do a regex find. For example, assuming you want to find "text", you could use this:
^(?!\s*?//).*?text
Caveats:
Assumes comments start with // as first non-whitespace characters. E.g. C# comment types
Doesn't work for comments at the end of code lines (only comments on their own lines)
Doesn't work with block comments, for example /* comment */
So overall it isn't perfect by any means, but depending how many hits you are getting, it might help to cut them down which can be useful if you have a lot of false positives in one-liner comments
The 'Find All References' function may suit you : it ignores all commented-out code and text in strings. CTRL+K, R is the keyboard shortcut.
(Note that it's designed for going from a specific instance of a search string to all other instances. so if you haven't already found an instance of what you're searching for, you would have to (temporarily) type one in to the editor window, then search. Also it's not available for all languages : I know it works fine for C#, though.)
We are confronting different search engines for our research
archives and having browsed the Xapian-Omega documentation, we
decided to try it out since the Omega option appears to be an
appropriate solution with several interesting search options.
We installed Xapian-Omega on a Linux Server (Deb 7) and tested
the setup with success. However we are unsure as to how one can
employ or perhaps even enable the use of Wild Cards or Regular
Expressions with Xapian-Omega.
We read that for Xapian one has to enable the Wild Card option
"QueryParser flags"
Could someone clarify this ?
ie. explain with or indicate a page with an example or two.
But we did not see much information regarding examples with Omega
CGI and although this latter runs well, wild card options
(such as * for the general wild card and ? as a single character),
do not seem to work as expected by default and they would be
useful, even though stemming and substrings etc may be functional.
Eg: It would be interesting to be able to employ standard simple
wild char searches with a certain precision such as :
medic* for medicine medical medicament
or with ? for single characters
Can Regexp be recognised with Omega ?
eg : sep[ae]r[ae]te(\w+)?
or searching for structured formats such as Email or Credit Card
Numbers or certain formula types in research papers etc.
In a note from Olly Betts long ago (Dev Mailing List) regarding
this one suggestion was to grep the index file but this would
defeat the RAD advantage of Omega.
Any examples of searches using Omega with Wild Cards or Regular
Expressions would be most appreciated ... even an indication of
a page where information regarding this theme is well presented
with examples illustrating how to develop advanced searches
using Xapian alone would be most welcome (PHP or Python perhaps).
(We are not concerned for the moment about the eventual
substantial increase in the size of the index size or in the
time to index the archive)
You can enable right-wildcards (such as "medic*") in Omega using $set{flag_wildcard,1} (covered in the Omegascript documentation), which enables FLAG_WILDCARD. There's a section in the user manual on using wildcards.
Xapian doesn't provide support for regular expression searching, although in theory I believe it would be possible to support, if potentially costly (depending on the regex). It would have to run the regular expression against unstemmed terms in the database, and then feed them into the search. Where it becomes difficult is if the regex expands to a lot of terms (eg just 'a' as a regex). There's also some subtlety in making it efficient; it's easy to jump through the term list to something with a constant prefix, and you'd want to take advantage of that if possible.
For your example of sep[ae]r[ae]te(\w+)?, it sounds like you actually want a combination of spelling correction (for the a-e substitutions, which you can enable using $set{flag_spelling_correction,1}) and stemming (for the trailing letters after 'te'; Omega defaults to English stemming, but that can be changed), or either wildcard or partial match support.
If you do need regular expressions for your use case, then I'd suggest bringing it up on the xapian-discuss mailing list. Xapian has moved on since the last discussion, and I believe it would be easier to build such support now than it was then.
James Ayatt: Thank you for your answer and help, my apologies for this belated reply, a distraction with other work.
We had already seen the Omegascript page but it was not clear to us how to employ these options with the CGI interface. Also the use of * seems to be for trailing chars, is that correct ? ie not for internal groups of words eg: omeg*ipt; there are cases where the stemming option would not be sufficient. We did not see an option for single wild chars, sometimes represented by ? in certain search engines. Could you comment here ?
Regarding the use of regular expressions we had immagined that it might not be quite as simple as one could hope. The examples mentioned in the preceding post were of course simple possible uses, there are of course many more. Your comment on using the stemming option seems appropriate.
In certain cases it could be interesting to enable some type of regexp option for the extraction of text forms, such as those mentioned. The quick extractiion of such text, perhaps together with some surrounding text could be very useful.
We will certainly try your proposal with the mailing list.
Thank you again.
If not, is there a de facto standard? Basically I'm writing a command line help text like so:
usage: app_name [options] required_input required_input2
options:
-a, --argument Does something
-b required Does something with "required"
-c, --command required Something else
-d [optlistitem1 optlistitem 2 ... ] Something with list
I made that from basically just reading the help text of various tools, but is there a list of guidelines or something? For example, do I use square brackets or parentheses? How to use spacing? What if the argument is a list? Thanks!
Typically, your help output should include:
Description of what the app does
Usage syntax, which:
Uses [options] to indicate where the options go
arg_name for a required, singular arg
[arg_name] for an optional, singular arg
arg_name... for a required arg of which there can be many (this is rare)
[arg_name...] for an arg for which any number can be supplied
note that arg_name should be a descriptive, short name, in lower, snake case
A nicely-formatted list of options, each:
having a short description
showing the default value, if there is one
showing the possible values, if that applies
Note that if an option can accept a short form (e.g. -l) or a long form (e.g. --list), include them together on the same line, as their descriptions will be the same
Brief indicator of the location of config files or environment variables that might be the source of command line arguments, e.g. GREP_OPTS
If there is a man page, indicate as such, otherwise, a brief indicator of where more detailed help can be found
Note further that it's good form to accept both -h and --help to trigger this message and that you should show this message if the user messes up the command-line syntax, e.g. omits a required argument.
Take a look at docopt. It is a formal standard for documenting (and automatically parsing) command line arguments.
For example...
Usage:
my_program command --option <argument>
my_program [<optional-argument>]
my_program --another-option=<with-argument>
my_program (--either-that-option | <or-this-argument>)
my_program <repeating-argument> <repeating-argument>...
I think there is no standard syntax for command line usage, but most use this convention:
Microsoft Command-Line Syntax, IBM has similar Command-Line Syntax
Text without brackets or braces
Items you must type as shown
<Text inside angle brackets>
Placeholder for which you must supply a value
[Text inside square brackets]
Optional items
{Text inside braces}
Set of required items; choose one
Vertical bar {a|b}
Separator for mutually exclusive items; choose one
Ellipsis <file> …
Items that can be repeated
We are running Linux, a mostly POSIX-compliant OS. POSIX standards it should be: Utility Argument Syntax.
An option is a hyphen followed by a single alphanumeric character,
like this: -o.
An option may require an argument (which must appear
immediately after the option); for example, -o argument or
-oargument.
Options that do not require arguments can be grouped after a hyphen, so, for example, -lst is equivalent to -t -l -s.
Options can appear in any order; thus -lst is equivalent to -tls.
Options can appear multiple times.
Options precede other nonoption
arguments: -lst nonoption.
The -- argument terminates options.
The - option is typically used to represent one of the standard input
streams.
The GNU Coding Standard is a good reference for things like this. This section deals with the output of --help. In this case it is not very specific. You probably can't go wrong with printing a table showing the short and long options and a succinct description. Try to get the spacing between all arguments right for readability. You probably want to provide a man page (and possibly an info manual) for your tool to provide a more elaborate explanation.
Microsoft has their own Command Line Standard specification:
This document is focused at developers of command line utilities. Collectively, our goal is to present a consistent, composable command line user experience. Achieving that allows a user to learn a core set of concepts (syntax, naming, behaviors, etc) and then be able to translate that knowledge into working with a large set of commands. Those commands should be able to output standardized streams of data in a standardized format to allow easy composition without the burden of parsing streams of output text. This document is written to be independent of any specific implementation of a shell, set of utilities or command creation technologies; however, Appendix J - Using Windows Powershell to implement the Microsoft Command Line Standard shows how using Windows PowerShell will provide implementation of many of these guidelines for free.
There is no standard but http://docopt.org/ has created their version of a specification for help text for command line tools.
yes, you're on the right track.
yes, square brackets are the usual indicator for optional items.
Typically, as you have sketched out, there is a commandline summary at the top, followed by details, ideally with samples for each option. (Your example shows lines in between each option description, but I assume that is an editing issue, and that your real program outputs indented option listings with no blank lines in between. This would be the standard to follow in any case.)
A newer trend, (maybe there is a POSIX specification that addresses this?), is the elimination of the man page system for documentation, and including all information that would be in a manpage as part of the program --help output. This extra will include longer descriptions, concepts explained, usage samples, known limitations and bugs, how to report a bug, and possibly a 'see also' section for related commands.
I hope this helps.
It may be a bit off-topic, but I once wrote two small tools that make creation and maintenance of command line tools help pages more efficient:
The MAIN DOCLET that generates an HTML document for the main method of a Java program by processing Javadoc comments in the source code
The HTML2TXT tool that formats an HTML document as a plain text (which is what we want our help texts)
I integrate these two tools in the MAVEN build process of my programs so they execute automatically on every build.
For example:
The relevant source file of my ZZFIND tool
The POM file that builds the project (and runs the two tools mentioned above)
Example output when ZZFIND is run with the --help command line option
Hope this is useful for others!?
I use the CSS formal notation for this.
Component values may be arranged into property values as follows:
Several juxtaposed words mean that all of them must occur, in the given order.
A bar (|) separates two or more alternatives: exactly one of them must occur.
A double bar (||) separates two or more options: one or more of them must occur, in any order.
A double ampersand (&&) separates two or more components, all of which must occur, in any order.
Brackets ([ ]) are for grouping.
Juxtaposition is stronger than the double ampersand, the double ampersand is stronger than the double bar, and the double bar is stronger than the bar. Thus, the following lines are equivalent:
a b | c || d && e f
[ a b ] | [ c || [ d && [ e f ]]]
Every type, keyword, or bracketed group may be followed by one of the following modifiers:
An asterisk (*) indicates that the preceding type, word, or group occurs zero or more times.
A plus (+) indicates that the preceding type, word, or group occurs one or more times.
A question mark (?) indicates that the preceding type, word, or group is optional.
A pair of numbers in curly braces ({A,B}) indicates that the preceding type, word, or group occurs at least A and at most B times.
If you need examples, see Formal definition sections on MDN; here is one for font: https://developer.mozilla.org/en-US/docs/Web/CSS/font#formal_syntax.
And here is a simple example from my own Pandoc's cheat sheet:
$ pandoc <input_file>.md --from [markdown|commonmark_x][-smart]? --to html --standalone --table-of-contents? --number-sections? [--css <style_sheet>.css]? --output <output_file>.html
I would follow official projects like tar as an example. In my opinion help msg. needs to be simple and descriptive as possible. Examples of use are good too. There is no real need for "standard help".
First of all, I finally made this a wiki, but I believe a "simple," straightforward answer is highly desirable, especially since the result would define a unified IDE behavior for everyone. More on the simple later.
In the past, I've blogged about what it means to have a well-behaved member selection drop down. If you haven't read it, do so now. :)
Visual Studio 2010 adds new features to the IntelliSense selection process that makes things ... not so easy. I believe there's great power we can harness from these features, but without a clean set of governing rules it's going to be very difficult.
Before you answer, remember this: The rules should allow someone "in tune" with the system to take advantage of the IntelliSense power with fewer keystrokes and less time than other solutions provide. This is not just about what you're used to - If you use a system as long and frequently as I do, relearning the patterns is trivial next to the time it saves to have a great algorithm behind it.
Here are the controllable axes:
Filtering: A "full" list contains every identifier or keyword allowed at the current location, without regard for the partially typed text the cursor is within.
Sorting: We (at least Visual Studio users) are used to the member selection drop down being sorted in alphabetical order. Other possibilities are partial sorting by some notion "relevance," etc.
Selection: Based on the currently typed text, we have the ability to select one item as the "best match." Selection states are:
No item selected
Passive selection: one item outlined, but pressing ., <space> or similar won't fill it in without using an arrow key to make it:
Active selection: one item selected, and unless Esc or an arrow key is pressed, a . or <space>, etc will auto-complete the item.
My previous set of rules restricted the manipulation to the selection axis. They took into account:
Characters typed as matched against list items with a StartsWith operation (prefix matching), with variants for whether the match was case-sensitive.
Previous completions that started with the same set of characters.
The following are additionally available and potentially useful, but not all have to be used:
CamelCase matches or underscore_separation ("us"): Long, expressive identifiers? Not a problem.
Substring matches: long prefixes hindering your selection speed? Not a problem.
Information available in the summary text, where available: I lean against this but I must admit it's come in handy in the Firefox address bar, so you never know.
The rules you write should address the axes (in bold above) in order. In my previous posts on the subject, the rules were very simple, but the additional considerations will likely make this a bit more complicated.
Filtering
Sorting
Selection
Just one addition or remark ...
IntelliSense should adapt to the context. In the case of Visual Studio, places where only subtypes of a specific type or interface may be used, the dropdown list should filter by these.
IList list = new (Drop down all the types implementing IList) - not all possible types!