This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: A straw proposal for help topics in DocBook


/ Michael Smith <smith@xml-doc.org> was heard to say:
| 1. Online-help peer to Set. Do we actually need one? What will the
|    processing expectations be for it? Do any of the existing help
|    systems -- HTML Help, Javahelp, or whatever -- provide any way for
|    packaging up sets of HTML Help files?

I think it's a good idea. I think it's fairly common to build
HelpProjects for individual components of a system but to sometimes
publish them as a master help-set.

| 2. Element names. If we do keep the peer to Set, I don't think we
|    should call it Helpset. I think Helpset is what the Javahelp DTD
|    uses as its primary wrapper for topics, and I sometimes see the
|    word "helpset" used generically to mean "online help file".

Good point.

|    I think Helpproject is good as the name for a set of topics; some
|    other possibilities: Helpfile, Helpvolume, Helpset. But I guess
|    Helpproject seems best.

So we need a new name for the set-of-projects wrapper.

| 3. Content model for the set-of-topics element (Helpproject). Does it
|    need to include the navigational components (ToC, LoT, Index)?
|    These seem useful only if authors want to manually author ToCs,
|    LoTs, and Indexes, instead of leaving it up to the
|    stylesheets/helpcompiler to generate them. Does anybody really
|    manually author those?

It is necessary to build them by hand sometimes. And even when it isn't,
there are systems that use an empty element (<toc/> or <index/>) to
identify where the auto-generated content should go.

|    So it looks like if we use a Section-like (instead of Chapter-like)
|    content model for Topic, it'll mean that Topics can contain only
|    recursive Sections, not numbered ones (Sect1-Sect5), and that
|    Topics can't contain Refentrys at all (or Simplesect).

I am strongly opposed to allowing Topics to contain any form of
sectioning element. They are not part of the sectioning hierarchy,
that's one of the main motivations for creating them (IMHO).

Perhaps HelpProjects should allow (topic|refentry)+...

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Never contend with a man who has
http://www.oasis-open.org/docbook/ | nothing to lose.--Graci\'an
Chair, DocBook Technical Committee |

----------------------------------------------------------------
To subscribe or unsubscribe from this elist use the subscription
manager: <http://lists.oasis-open.org/ob/adm.pl>


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]