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. :)
------------------------------------------------------------------------------
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
