Thread: [Autogen-users] "stanza" processing, i18n, ...
Brought to you by:
bkorb
Menu
▾
▴
autogen-users
|
From: Harlan S. <st...@nt...> - 2010-12-27 23:11:16
|
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.
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'.
I was noting that I'd like the 'detail' stanza to have certain tags get
expanded (things like the program name, etc).
Right now, the detail stanza is "plain inhaled text" and it is not
post-processed.
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
- a function a la: expandStanza("stanzaName", "tagtype")
that would mean something like:
Scan the symbol table looking for 'stanzaName-tagtype'.
If it is there, give it to me unmodified.
If it is not there, start searching first for stanzaName-texi, then
stanzaName-mdoc, ... (per the preferred tag type list mentioned above)
and as soon as you find the first one use the translation stuff
Kapila wrote to convert it to the desired "tagtype".
The other reason I like this is that it makes it much easier to support
new tag types and have them become automatically supported in existing
.tpl files.
I'm suggesting this because I do not want to have to maintain multiple
instances of a given stanza (for different output formats) unless I
absolutely have to.
--
Harlan Stenn <st...@nt...>
http://ntpforum.isc.org - be a member!
|
|
From: Bruce K. <bru...@gm...> - 2010-12-29 21:32:00
|
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.
|
|
From: Harlan S. <st...@nt...> - 2010-12-29 23:51:47
|
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
|
|
From: Bruce K. <bru...@gm...> - 2010-12-30 00:51:58
|
On 12/29/10 15:51, Harlan Stenn wrote:
>> 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.
Hmmmm. What you are asking for is multiple "doc-section"s that
have a "ds-type" of "SEE ALSO" (for example) and having some way
to distinguish them, depending upon output format. Sort-of a
"bypass output pattern" type of thing:
ds-ignore = pod, mdoc;
Of course that can be done, but:
> Do you have a guess at the timeline for this? I'm ready to start
> testing and using it...
My priority right now is finding employment. Sorry.
You can find the beginnings of it by searching for
"doc-section" in the autoopts/tpl directory of the "pre"
releases.
>> 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.
It is a trade off between maintaining multiple copies of
the same basic text vs. the hassle of figuring out a canonical
form that can be directly converted into all the desired
output forms. If someone prefers maintaining multiple copies
then that means they prefer maintaining multiple copies.
>> 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.
Make an edict:
All documentation shall be in mdoc format.
If you are not familiar with mdoc format,
that is fine. We'll take your initial documentation
and convert it to canonical form and then emit the
needed documentation. The official source shall be mdoc.
> 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".
Ah, yes, the extra blurb at the end of the usage text output.
It does need some markup capabilities and the markup needs to
get stripped for usage output and it must not require markup.
I am open to suggestions from anyone. :)
|
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X