Hi Harlan,
On 12/27/10 14:26, Harlan Stenn wrote:
> The following ramble is not fully thought-out.
>
> I was thinking about how I'd like to be able to support i18n of our
> docs, specifically looking toward the stanzas in a .def file.
I've gone to some trouble to try to get the libopts messages
into a translatable form. However, I don't think any attempt
has been made to translate long option names, etc. so I confess
to believing that there are many unresolved problems with it....
> While doing this, I also was again reminded that with Kapila's recent
> work we can now expect to see things like 'prog-man-descrip' or
> 'prog-mdoc-descrip'.
Remember, this stuff is still in flux. I am rewriting it
as "doc-sections" and each section describes its format:
doc-section = {
ds-type = "SEE ALSO"; // etc.
ds-format = man; // "texi", "mdoc", etc.
ds-text = <<- _EOF_
whatever
_EOF_;
};
> Given that there are a number of templates that "share" stanzas, and
> that we "need" and now "have" the ability to translate tags from one
> format to another, I'm thinking that it would be Swell if there were
> some internal autogen functions and variables that would "help out"
> template writers, such as:
>
> - a list of the preferred tag types, defaulting to, say:
>
> texi mdoc pod man html text
The preferred input is going to be that which has sufficient
range of expressiveness to be able to be translated into the
other forms. I think that means texi and certainly would not
be plain text. mdoc and man seem too limited and I am not familiar
with "pod", though these may be sufficient given the limited
expressiveness needed for usage documentation.
> - a function a la: expandStanza("stanzaName", "tagtype")
>
> that would mean something like:
That is just a Scheme function away from being done.
All you need to do is write the transform as a Scheme function.
If it is generally useful, it can be incorporated into the
added-on templates. Something a bit more polished than this:
(shellf "%s <<_EOF_\n%s\n_EOF_"
(find-file (string-append (get "ds-format") "2man"))
(get "ds-text"))
but that conveys the general idea: look up a translator script
based on the input format and the output format and have it filter
the related text. For extra credit, you can put the program
name into the environment and have such a script look for magic
markers:
(shellf "export prog_name='%s'" (get "prog-name"))
and then replace markers like "@@PROG-NAME:italics@@"
What I am sure I don't want to do is get into defining a new
syntax for substituting values within values. I think that
there would lie madness. Sorry.
------------------------------------------------------------------------------
Learn how Oracle Real Application Clusters (RAC) One Node allows customers
to consolidate database storage, standardize their database environment, and,
should the need arise, upgrade to a full multi-node Oracle RAC database
without downtime or disruption
http://p.sf.net/sfu/oracle-sfdevnl
_______________________________________________
Autogen-users mailing list
Autogen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/autogen-users
