Is there any way to write multilanguage documentation using POD? If no, what should I write it in (I already have POD documentation in English, so I will want to convert it and then translate)?
If you're asking whether POD supports non-English encoding, the answer is a resounding YES. Here's an example of brian d foy's article (in POD format) translated into Russian: http://perlrussia.ru/article/brians-guide/brian%27s_guide.ru.pod
If you are wondering if it's possible to stick multi-language POD into the same file, there's a fairly curious example here:
http://cpansearch.perl.org/src/HIO/Unicode-Japanese-0.47/lib/Unicode/Japanese.mlpod
It uses Pod::Multilang
However, i'm not entirely certain how (or even if) it works, as I could not find two examples of html generated straight from that mlpod.
See http://perldoc2.sourceforge.net/ - this is a project for international perldoc
If you're preparing your module for distribution on CPAN, create separate .pod files for the translations of your documentation.
For example, if you have included the English documentation in My/Module.pm, you could create the files My/Module-jp.pod, My/Module-ru.pod, etc.:
=head1 NAME
My::Module-pl - Atin-lay Ig-pay ocumentation-day or-fay y-may odule-may
=head1 ERSION-VAY
1.01
=head1 ESCRIPTION-DAY
...
Related
Searching for Devel::Peek at metacpan.org gives the following screen shot:
Why is the module listed three times? (It looks a little bit strange, and could easily confuse the user..)
Oddly enough, there's one missing. The following are Devel::Peek's official distributions:
perl
Devel-Peek
These two distributions are returned when searching search.cpan.org, and the only two distributions returned when searching search.cpan.org.
Being part of the perl distribution and part of its own distribution is called being a "dual-lifed" module. It allows the module to be bundled with Perl without having to upgrade Perl to upgrade the module.
I don't know why meta::cpan doesn't pick up the official distribution, and I don't know why it doesn't flag the other distributions as unofficial. You could alert the site's maintainers of the problem.
Conversely, I don't know why search.cpan.org doesn't return CookBookA and CookBookB, and why it doesn't flag theses other distributions as unofficial when one goes to it directly. I think it has to do with the fact that Devel::Peek is only present as a documentation file (.pod) —not a module (.pm)— in them.
I've searched around the web, and haven't found any procedure or tool that can distinguish those .docx files that are encoded as Strict ECMA-376 and those that are not. (same drill for .xlsx files) Most discussions center on which formats are supported by a given app, e.g. LibreOffice, but not how to distinguish files.
Dovetail question: 2. Does anyone know of any documentation that lays out the differences in the four editions of ECMA-376? http://www.ecma-international.org/publications/standards/Ecma-376.htm
On that page, you'll see first edition, second edition, third edition, fourth edition. First edition was 2006, and fourth edition is Dec 2012. None of the documentation appears to describe the revisions from one edition to the next, no "What's New in this edition" or anything like that. (In some cases they note structural changes, like a topic that was housed in Part 1 last time is now in Part 2, etc.)
Wikipedia describes the structural contents of the first two editions...: https://en.wikipedia.org/wiki/Office_Open_XML#Versions
...but has nothing to say about third or fourth editions, or substantive changes between the first two. Can anyone point me to documentation that lays out the iterative changes?
(ECMA-376 is normally mirrored by ISO 29500. ISO might document revisions, but their pubs are paywalled, and not just any paywall, but a 352 Swiss Franc paywall, which at today's exchange rates comes to $394.20...)
There are a couple of things to your questions:
Difference between Strict and Transitional
The main difference between Strict documents and Transitional documents is namespaces. The namespaces in Strict all contain #purl.org", as far as I remember, whereas namespaces in Transitional contain the word "microsoft". See the exact strings in Part 1 of OpenXml Standard for Strict and Part 4 for Transitional.
I do not think there is such a document available - and neither for the ISO-version.
And finally - you say that ECMA is mirrored by ISO. It is actually the other way around. Whenever ISO publishes a new version of the standard, an (almost) exact copy is published by ECMA (with their letter-head etc) afterwards.
And finally, finally, ISO OpenXml standard is free of charge. You can find the latest edition at http://standards.iso.org/ittf/PubliclyAvailableStandards/index.html (search for "29500" on the page).
Should you wish to look a bit into what we do in the ISO working group, this is a good start: http://jtc1sc34.org/wg4 .
Jesper Lund Stocholm
Appointed Expert to ISO SC34 committee working with OpenXml.
According to section 17.2.3 of Ecma Office Open XML Part 1, the document element of the main document story will have an attribute "conformance" that specifies the conformance class. This can either be strict, or transitional. If the attribute is omitted, the default value is transitional.
Annex M of Ecma Office Open XML Part 1 (page 5028) documents the differences between ECMA-376:2012 and ECMA-376:2006.
We consider to use Minilla or Dist::Milla for our perl development. Declaring dependencies is done via cpanfile. I expected to find an exact definintion of what and how can be declared. But
perldoc cpanfile :
Shows only the principal usage. 'SEE ALSO' section does not help.
perldoc Module::CPANfile: same as cpanfile.
perldoc cpanfile-faq: no explanation of the exact syntax or a link to it, only
Familiar DSL syntax
This is a new file type, but the format and syntax isn't entirely new.
The metadata it can declare is exactly a subset of "Prereqs" in
CPAN Meta Spec.
The syntax borrows a lot from Module::Install. Module::Install is a
great way to easily declare module metadata such as name, author and
dependencies. cpanfile format is simply to extract the dependencies
into a separate file, which means most of the developers are
familiar with the syntax.
Web : I found ( but does not answer my question )
https://speakerdeck.com/miyagawa/cpanfile
http://weblog.bulknews.net/post/44963580392/what-is-cpanfile-and-why-do-i-want-to-use-it
http://blogs.perl.org/users/lestrrat/2013/03/the-main-problem-with-cpan-modules-on-github.html
Does anybody know where to find an exact description of the cpanfile syntax/format ?
I installed Module::CPANFile and perldoc cpanfile and perldoc cpanfile-faq were available.
The POD for cpanfile states:
[the] cpanfile specification (this document) is based on Ruby's
Gemfile http://gembundler.com/man/gemfile.5.html specification.
The link in the cpanfile manual page is broken. It should point to: http://bundler.io/v1.3/man/gemfile.5.html
cpanfile is designed to "backwards compatible" with Module::Install DSL syntax and is "convertible to CPAN::Meta::Prereqs" and inspired by CPAN::Meta Spec v.2 etc.
As I understand it cpanfile is somewhat of a "meta-format" and fits into a range of TIMTOWTDI approaches (see miyagawa's blog describing cpanfile), compatible with Module::Install and mostly self-documenting. For example if you run mymeta-cpanfile inside a directory with META files it will build a cpanfile for you; you can write a script that describes prerequisites from CPAN::Meta::Prereqs and then $file->save('cpanfile'); to write a cpanfile.
As for Dist::Milla, in the tutorial (see the POD included with Dist::Milla) miyagawa points out that
"If you decide to manually construct [a] new cpanfile, the format is mostly compatible to Module::Install's requirement DSL". The tutorial also gives a short example.
I think it would be fair to ask miyagawa to clarify the status and use cases of the cpanfile specification/format in the documentation for the distribution. That and a few more examples would answer questions like yours. He has mostly done the work on this already - it is just not all in one place.
Christian Queinnec has written a masterpiece called LISP In Small Pieces, which features eleven Lisp Interpreters and two Lisp compilers.
When you go to download the code from the website here - it has the comment:
The programs of this book are available on the net.
These programs used to run with some Scheme systems around 1994.
Any idea:
(a) What Scheme systems these ran on at the time, and more importantly;
(b) What Scheme systems these would run on today?
There's a lot of programs in there. I did a few tests to see how well I could answer this without having to try them individually. There are 131 files in the tarball with extension ".scm". However there appear to be Scheme programs with other extensions such as .bgl. So I did a search for files containing 'L i S P' in the first five lines. That yields 173 files. I tried running all of these on my preferred Scheme implementation. 31 of these run without error. Almost all of these are in the "src" directory. So the language-specific programs really do seem language-specific. Let's look at one of the src/ files that failed, "chap9z.scm". It's choking on define-abbreviation. I don't know the origin of this symbol, but it's not defined anywhere in guile. But all of its uses could be performed by guile's syntax-rules.
Some Scheme implementations that existed in 1994 still are still around and maintained: Scheme 48, Chez Scheme, Gambit, Bigloo, MIT Scheme and SCM.
Probably the code from LiSP will run in other modern Scheme systems such as Guile or Larceny.
Personally, I would recommend using Racket. Most likely, much of the code will run in #lang racket with no changes, and there's no requirement to use [] (but your code may be easier to read :). Things that don't work are probably easy to fix, and you can also use the R5RS language implementation provided by Racket which will likely work for all of the code.
(a) What Scheme systems these ran on at the time
The Makefile in the source tarball from the author's website has targets for running the code under bigloo, elk, gambit, mit-scheme, scheme2c, and scm.
The Makefile mentions SCM 4e1 and Bigloo 1.9d as known working versions, though I haven't tested them myself. I didn't find any mention of specific versions for the other schemes.
(b) What Scheme systems these would run on today?
The code in this github repo has been updated so that almost all of the tests in the included test suite pass with current (as of 06/2014) versions of bigloo, gambit, and mit-scheme.
If you just want to be able to run the code and follow along with the book, one of those schemes should work for you.
[full disclosure: I'm the owner of the repo and I'm a Scheme noob. The code in the repo is WOMM certified, but your mileage may vary.]
If, on the other hand, you're not content to use bigloo / gambit / mit-scheme, it shouldn't be too hard to add support for guile / racket / insert-favorite-scheme-here. Use one of the book.* files as a starting point, e.g. gambit/book.scm or mitscheme/book.mit. If you can get a version of book.scm to load in your favorite scheme, then have a look at the test.interpreters make target, and finally the grand.test target to verify things are working as expected.
The included README file states:
These files were tested with a Scheme interpreter augmented with
a test-suite driver (tester.scm),
the define-syntax and define-abbreviation macros (using
Dybvig's syntax-case package),
and an object system: Meroonet (meroonet.scm).
Bigloo, Scheme->C, Gambit, Elk or SCM can be used. The first three are
better since a specialized interpreter may be built that contains a
compiled Meroonet and compiled hygienic macros.
Apparently Appleby has posted an updated version of the source code. Racket is missing though )=
See https://github.com/appleby/Lisp-In-Small-Pieces
What's the best way to author man pages? Should I write using the standard man macros, or is there some clever package available now that takes some kind of XML-ified source and can output man pages, HTML, ASCII, and what not?
Thanks
I have previously used the GNU version of nroff called groff to write man pages.
Nice intro article on it here:
http://www.linuxjournal.com/article/1158
Doxygen is what you are looking for.
Keep in mind that it is designed to document source code but you could easily adapt it.
It can generate html, pdf, and latex documentation too.
If you are looking at writing once and generating different output formats such as manpages, HTML, plain txt, or even PDF, then docbook should work best.
A tool that is commonly used in the Tcl community is doctools which can produce a restricted (but useful) subset of the manpage format, suitable for rendering with groff or nroff. It can also generate both plain text and HTML directly.
For my atinout program I have been using ronn which lets you write man pages in a very, very readable markdown like syntax. I am extremely happy with it.
atinout(1) -- Send AT commands to modem, capturing the response
===============================================================
## SYNOPSIS
`atinout` <input_file>|`-` <modem_device> <output_file>|`-`<br>
`atinout` `--version`<br>
`atinout` `--usage`<br>
`atinout` `--help`<br>
## DESCRIPTION
**Atinout** reads a list of AT commands. It sends those commands one by one
to the modem, waiting for the final result code for the
currently running command before continuing with the next command in
the list. The output from the commands is saved.
...
see the whole page here.