Hi Bruce,
Bruce wrote:
> 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....
Makes perfect sense, and we're on the same page. I just wanted to
mention it to be sure we were aware of it as we forged ahead.
> > 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, including .man formatting tags
> _EOF_;
> };
I think I really like that idea, and it would be OK to have the same
ds-type in a different stanza with a different ds-format, right? I
mention this because there may still be times when the "source"
ds-format does not translate to a "target" format the way we want, and
the easy fix for that would be to also provide the stanza that is
already in the desired format.
Do you have a guess at the timeline for this? I'm ready to start
testing and using it...
> > 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.
That would be nice, but I know I cannot force that on at least some of
my users. In this case, reality will bite me.
> 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.
I pretty much (and possibly completely) agree. I do believe that mdoc
may be rich enough. Kapila may know more about this.
But again, I am "forced" to let certain users dictacte the tag format
they want to use, and I must allow them that. If this user decides to
cut/paste their text using html tags, that's their choice. What I will
do, after the fact, is take that stanza and add in another copy that
will be in .mdoc or .texi (most likely, it depends) and then we'll all
be happy.
> > - 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.
I almost understand :)
Where this is coming from on my end is the "detail" stanza, as I'm
hoping that we can get things like boldface and underlining working
there, but to do that easily means translating from "some tag format" to
"plain text".
H
------------------------------------------------------------------------------
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
