Is there a best practices guideline for writing man pages?
What should be included in the layout? The standard ones are:
NAME
SYNOPSIS
DESCRIPTION
EXAMPLES
SEE ALSO
There are others like OPTIONS, AUTHOR.
As a user what would be useful to have? What isn't helpful?
If you cannot find any old bound copies of 1970s Bell Labs "troff" documentation, which had some nice sections on writing man pages, :-) then I'd suggest trying out Jens's "HOWTO" on writing man pages over at his site.
The Unix 7th Edition manuals are available online in a variety of formats.
A BUGS section is nice, and an EXAMPLES section is always useful. Some man pages contain a
FILES section which lists related configuration files, or ENVIRONMENT section detailing any influential environment variables.
To be clear, what sections or type of information are useful to users depends on the nature of the program or utility that you are documenting.
There is a canonical man page outline distributed with UNIX systems, or at least usually there is. In general, I'd put in all the fields, and include a line like "none" if it doesn't apply.
One thing which people sometimes forget to put in manual pages is the meaning of the return value of the function. It's easy to forget, but the omission can make life much harder for people who have to use your function. Also, a simple code segment in the SYNOPSIS or a good minimal working EXAMPLE is very useful.
One thing that I often do with man pages is to try to find a related command, even though I know the thing I'm looking at doesn't do what I want. In this case, the SEE ALSO is great.
It depends on what your software does. If it is a small stand-alone application, I would certainly put the AUTHOR section in the man page so that if users find bugs they can easily find an email address to report the bug to you.
As for best practices, none that I know of, other than that the man page should be concise, detailed but not contain too much information that is not required, if it is just a tool the inner workings are not required for example.
Related
Is the encoding of risc-v instructions to opcode bits standardized? If so, where can I find the encoding table at least for the base 32I instructions?
I guess it is always a good idea to keep up to the specs on https://riscv.org/specifications/. There chapter 25 lists in details how to encode the instructions. I also liked http://riscvbook.com very much.
Regards Joachim
It looks like I found it in github.
https://github.com/riscv/riscv-opcodes/blob/master/opcodes
The tables in The RISC-V Reader book that Joachim mentioned are very good (https://riscvbook.com). Even if you don’t have the book, there’s a PDF version available for free in Spanish (and some other languages), which may be enough for your purposes.
Barring that, I find the PDFs from the rv8 project concise, and really useful: https://github.com/rv8-io/rv8/tree/master/doc/pdf. (It's information that of course is present in the specs, but I couldn't find a short, 10-page document there containing it all.) It’s generated from the riscv-meta project which has machine-parseable descriptions of the ISA, which may be useful as well depending what you’re trying to do.
I am having a very difficult time finding any documentation about how the various parts of the Inno Setup Wizardform are hooked together.
Using various answers here on StackOVerflow I have gathered some information but most of the time these are inferences rather and I'm not confident I really have a good grasp.
I have looked at the online help available at http://www.jrsoftware.org/ishelp/index.php and specifically the section on Support Classes Reference but it just gives me a list of all the parts of the wizard form. I really would like more information about how things like the InstallingPage and the InnerPage relate. I've looked through the listing of topics as well and nothing appears to relate to the question I have.
I'm just having a very difficult time grasping how all of those various parts hook together and where each part is in a hierarchy either visual or logical.
I guess I could go look at the source code for Inno Setup but I thought it'd be worth asking here first before diving into an unfamiliar code base in a language I've only been poking at for two days. If that is my only recourse, I guess I'll have to.
I would like more information about how things like the InstallingPage and the InnerPage relate.
No, WizardForm internals are not documented.
You might read the source.
A code search reveals that the search terms do not occur that often.
https://github.com/jrsoftware/issrc/search?q=InnerPage
https://github.com/jrsoftware/issrc/search?q=InstallingPage
This is the source for the Wizard itself and it's form.
The pages are hooked together via RegisterExistingPage().
I am trying to figure out how to get/set file access information through getxattr of "system.posix_acl_access". Suprisingly, a Google search resulted in no such link in the first pages. The man pages mention the attributes, but give no details beyond saying they are standard.
Assuming I wish to actually use them, is there any better option than reading the source for coreutils? I'm wondering what other attributes, under system or otherwise, I might be missing this way.
Edited to add:
The ACLs themselves are documented in POSIX 1003.1e (available for download here. It is an abandoned standard, but as Linux implements it, and coreutils (in particular, cp) uses it (at least the way it is compiled on Ubuntu), then it is relevent, standard or not.
This question, however, relates not to the particular entry, but for an extensive list of all standard extended attributes (though it seems, from reading sources, that on Linux only system.posix_acl_access and system.posix_acl_default exist).
I need to find figures that show how many programmers world wide, has each of the following languages as their primary programming language.
C
C++
C#
Object-C
Java
JavaScript
VB.NET
VB6 (or older)
VBA
PHP
flash scripts
Ruby
Does anyone know of such comparison figures?
If not. Do you know of a good way to research this?
I could compare the number of tags here at stackoverflow and the number of articles for each language at sites like codeproject. This would give me a good idea.
But if you can suggest other ideas how to find these numbers I will be greatfull.
/Thomas
A very common site that does this is the TIOBE index. It basically searches for programming languages in major search engines and compares the results, and it shows you some history. The only problem is that C/C++/C# are not distinguished very well, therefore C is more dominant than you'd expect (not to mention that search results include many pages where many languages are listed, like programming FAQs). But in general, TIOBE gives a good idea, I think, and it should get better, since at least Google tends to know the difference between zero, two or four pluses.
Have you tried TIOBE index?
In general this is hard to measure because every approach has a lot of drawbacks.
TIOBE and others that are based on search results e.g. do not tell anything of what is actually used but just what is highly ranked by google (You can even see that just Google changing a bit of their results in 2004/2005 completely mixed TIOBE). And moreover they have the problem that lots of search-terms are ambiguous (Like Java which IS also an island, Ruby which also exists as gem, Python which is a snake and others which have alternative meaning). Another problem with search based is that most things put into the web stay up forever which means it is irrelevant if it is CURRENTLY interesting. If a C resource was put up in 2002 it likely still is available today (which hugely overrates leading or older languages.)
Here one is an interesting approach based on the number of book sales. (This at least eliminates the ambigous problem, but comes with others.)
Wikipedia also has a small article about the topic.
Try Google trends (see an example). In addition, check sites like freshmeat.net and note the number of projects in each language. That's only open source projects and many people will use a different language for their hobby projects than at work (i.e. one that sucks less).
Next, look for sites which offer job openings. I don't have a good link handy but this Google query should get your started.
not yet!!!!!!!
That's only open source projects and many people will use a different language for their hobby projects than at work (i.e. one that sucks less).
Next, look for sites which offer job openings. I don't have a good link handy but this Google query should get your started.
In my initial days of using linux I usually had to search google to know the command for
doing a particular task. Once I have the command name, i can view its usage using man command-name.
Similarly I was thinking of some utility which can tell the command to do a particular task if the task to be done is specified as an argument and opens the man page for that command
e.g:
findUtilty "find all files in a directory"
output:
ls
find
I want to know if some utility of that kind exists, if so it will be very handy especially for newbies.
If not then i may like to implement it.
thanx,
Not as nice as you are asking about, but
apropos <keyword>
and
man -k <keyword>
can be very useful.
Parsing natural language is hard because there are thousands of ways to rephrase one sentence. Google does it best as far as I know. So, there is no such tool. There are handy and practical manuals that makes it easy to find the right tool for the job. Also, there is a huge community behind core-utils (and linux in general), so try both forums and IRC. Often, the latter is the fastest. And people tend to parse natural language as expected :)
apropos will do something like you suggest.
I guess it is: List of Unix utilities # Wikipedia
on Debian (and presumably derived systems) this is also useful:
sudo apt-cache search <keyword>
Few years ago NetBSD decided to rewrite its apropos. The new implementation does a full text search with results ranked in order of relevance. It comes close to what you have asked. See the output here
https://man-k.org/search?q=find+all+files+in+directory