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.
H. What you are asking for is multiple doc-sections 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. :)
--
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
