OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [dita] DITA 1.3 documentation -- shall we remove the Contains and "Contains by" tables


I use the HTML version, so that would be fine with me.

Thanks and best regards,

--Scott

Scott Hudson |  Pelco by Schneider Electric | United States | Standards Lead
Ph: +1-970-282-1952  | M: +1-720-663-7268 | Site: pdn.pelco.com |
scott.hudson@schneider-electric.com





On 9/12/12 8:34 AM, "Robert Anderson" <robander@us.ibm.com> wrote:

> I think Kris may be addressing this with her question about which format
> are used, but -- does anybody use the contains/by links in the PDF? I
> personally use them relatively often, but only in the HTML - apart from
> checking that they work, I don't think I've used them in PDF. So, another
> idea could be to include them where they are in HTML, but filter them out
> in PDF, provided OASIS rules allow for that.
> 
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit (http://dita-ot.sourceforge.net/)
> 
> 
> 
> From: "Bissantz, Debra" <Debra.Bissantz@lsi.com>
> To: "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
> Date: 09/12/2012 10:28
> Subject: RE: [dita] DITA 1.3 documentation -- shall we remove the
>             Contains and "Contains by" tables
> Sent by: <dita@lists.oasis-open.org>
> 
> 
> 
> I also use the tables to navigate through the spec. I would be disappointed
> to see these moved to an appendix. In the HTML version, that would require
> additional clicks to get to elements in the content tables.
> 
> I also don't use the PDF version as much as I use the HTML version. It
> takes quite a while for the PDF to open. I'm also pretty familiar with the
> domains, so I know where to start looking for an element.
> 
> I agree that moving the alphabetical list to the front would be helpful.
> 
> - Deb
> 
> -----Original Message-----
> From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On
> Behalf Of Noz Urbina
> Sent: Wednesday, September 12, 2012 8:18 AM
> To: Jang F.M. Graat
> Cc: dita
> Subject: RE: [dita] DITA 1.3 documentation -- shall we remove the Contains
> and "Contains by" tables
> 
> I second that Jang!
> 
> My usual method is:
> go to the ToC
> do a search for the element I want
> use the tables to navigate around
> 
> -----Original Message-----
> From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On
> Behalf Of Jang F.M. Graat
> Sent: 12 September 2012 15:45
> To: DITA TC
> Subject: Re: [dita] DITA 1.3 documentation -- shall we remove the Contains
> and "Contains by" tables
> 
> Hi Robert,
> 
> I know there is an alphabetical list of elements in the specs. It may just
> be the awkward location of that list in the DITA 1.2 specs that makes
> people use a text search to find an element. Once you have found the
> element you are looking for, the Contains / Contained by tables are
> wonderful methods to traverse the DITA model, jumping from one element to
> its children or parents. I have used those tables more often than the table
> of contents or any other navigation. Taking the tables out of the text flow
> would be pretty devastating.
> 
> Many products have a Quick Reference and usually that document is the first
> thing you find when opening the box. In the DITA 1.2 specs this Quick
> Reference is buried two levels deep in section 3.5. Moving it to where it
> should be (immediately after or even before the Table of Contents) would be
> an easy fix for a problem that is mainly disclosure - not availability - of
> information.
> 
> Ciao
> 
> Jang
> 
> JANG Communication
> Coaching - Copywriting - Consulting
> Amsterdam - Netherlands
> Tel.  +31 20 755 8466
> Cell +31 6 5478 1632
> http://www.jang.nl
> 
> On 12 sep. 2012, at 15:28, Robert D Anderson wrote:
> 
>> For what it's worth, we tried having an alphabetical list of elements
>> at the end of the language section, but something tells me it isn't
>> being noticed by most people. I'm not sure how to improve that. The
>> lists are available with a couple of groupings, or as one long list:
>> http://docs.oasis-open.org/dita/v1.2/os/spec/element-quick-reference.h
>> tml
>> 
>> A couple of ideas - the specification previously came in multiple docs
>> (architectural specification and language specification). We could
>> have a companion doc that is part of the specification deliverable,
>> linked to from the main page (like we link to the DTDs and XSDs), and
>> store the contains/contained-by items in there (linked to from the
>> main language spec). That could be done as a single doc, or as
>> individual docs (which would easily let us include only the learning
>> modules with a future learning package). If we did that, and if we
>> found a way to simplify the attribute tables (big if), then the PDF
>> could conceivably become small enough to print out. I know, a fantasy...
>> 
>> A less advanced idea would be to store the content models in an
>> appendix, which would at least mean that a search from the front of
>> the PDF would hit the element descriptions before hitting the content
> models.
>> 
>> Robert D Anderson
>> IBM Authoring Tools Development
>> Chief Architect, DITA Open Toolkit (http://dita-ot.sourceforge.net/)
>> 
>> 
>> 
>> From:   "Jang F.M. Graat" <jang@jang.nl>
>> To:   DITA TC <dita@lists.oasis-open.org>
>> Date:   09/12/2012 00:58
>> Subject:   Re: [dita] DITA 1.3 documentation -- shall we remove the
>>            Contains and "Contains by" tables
>> Sent by:   <dita@lists.oasis-open.org>
>> 
>> 
>> 
>> Hello all,
>> 
>> I agree with Tony that the problem is the search method, not its
>> availability. Having an alphabetical list of elements, possibly having
>> more than one such list - grouped per domain - as hyperlinks in an
>> obvious location (appendix ? or up front immediately following the
>> TOC) would do a lot of good for readers of the specs. Full text search
>> is a must if you want to find that certain phrase you know you have
>> seen before but forgotten where. Paging through those 1200 pages to
>> find the phrase is almost impossible to do. Killing the full text
>> search because some people use it in the wrong way is a bad choice.
>> Removing the tables is a bad choice, too. Rethinking possible ways of
>> disclosing the information is a good one.
>> 
>> Ciao
>> 
>> Jang
>> 
>> JANG Communication
>> Coaching - Copywriting - Consulting
>> Amsterdam - Netherlands
>> Tel.  +31 20 755 8466
>> Cell +31 6 5478 1632
>> http://www.jang.nl
>> 
>> On 12 sep. 2012, at 02:54, Tony Self wrote:
>> 
>>> Greetings all
>>> 
>>> If the problem is in text searching in PDFs, could we guide readers
>>> to
>> using the index as a means of better locating information? While
>> disabling the search function would push readers to use the index, it
>> may cause more angst than it relieves. Sorry this isn't a brilliant
>> solution, but I suspect there isn't one!
>>> 
>>> Cheers
>>> 
>>> Tony Self
>>> 
>>> 
>>> 
>>> From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On
>> Behalf Of Kristen James Eberlein
>>> Sent: Wednesday, 12 September 2012 6:50 AM
>>> To: DITA TC
>>> Subject: [dita] DITA 1.3 documentation -- shall we remove the
>>> Contains
>> and "Contains by" tables
>>> 
>>> As we start working on DITA 1.3 documentation, we need to consider
>> whether to include the Contains and "Contains by" tables in the
>> Language Reference topics.
>>> 
>>> Pro = Useful information
>>> Con = Makes it impossible to search the spec and find information
>>> about a
>> specific element, since there are so many false hits. For example, if
>> you search the PDF version for indexterm, you get over 130 false hits
>> before you land on the actual topic.
>>> 
>>> Best,
>>> Kris
>>> 
>>> Kristen James Eberlein
>>> Principal consultant, Eberlein Consulting Co-chair, OASIS DITA
>>> Technical Committee Charter member, OASIS DITA Adoption Committee
>>> www.eberleinconsulting.com
>>> +1 919 682-2290; kriseberlein (skype)
>> 
>> 
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
>> For additional commands, e-mail: dita-help@lists.oasis-open.org
>> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: dita-help@lists.oasis-open.org
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: dita-help@lists.oasis-open.org
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: dita-help@lists.oasis-open.org
> 
> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: dita-help@lists.oasis-open.org
> 
> 
> ______________________________________________________________________
> This email has been scanned by the Symantec Email Security.cloud service.
> ______________________________________________________________________



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]