incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gunnar Tapper <>
Subject Re: [DISCUSS] Documentation
Date Mon, 14 Nov 2016 02:03:31 GMT
Hi Jonathon,

Thanks for the great information! I'll definitely look into supporting ePub
and Mobi formats as well as thinking through if the process can be

As for multi-book, I fell in love with it back when using FrameMaker. A
word processor supporting emacs commands can never be wrong. :)



On Sat, Nov 12, 2016 at 12:45 PM, toki <> wrote:

> On 12/11/2016 04:09, Gunnar Tapper wrote:
> > For documentation, I couldn't find an easy way to do multi-chapter books,
> If AOo is meant, use Master Documents.
> There are a couple of use cases  (^1 ), where Master Documents don't
> work. In those instances, virtually every solution will fail. (^2)
> > but I also have people that prefer to review/read documents on
> Kindle-style devices. PDF helps with that.
> Most eBook readers, and smart phones do not handle PDFs very well. For
> those, either ePub or Mobi work much better.
> > But overall, my main motivation is to get others to write:
> Writing good documentation is a long, arduous process. It involves
> explaining the various options, including when and how to use them.
> Options that the individual writing the documentation might not be aware
> of.
> Taking a trivial example:
> * Export PDF;
> * Export as PDF;
> * Print (to PDF);
> * Print (as PDF);
> * Send Email as PDF;
> Five options, each of which creates a slightly different PDF.
> Easy to explain, with blatantly obvious differences.
> For a slightly harder example to explain, look at ligatures in English,
> using the Latin Writing System. Yes, it works, but the results are much
> better when both CTL and Asian text support is turned on.
> For something that is not only not obvious, but incredibly difficult to
> track down, the presence or absence of metadata in the fonts that are
> used, affects whether or not AOo utilizes the font correctly. (That you
> paid US$10,000 for the typeface, does not mean that the metadata is
> either present, or accurate. Nor does the fact that the typeface was
> gratis, mean that the metadata is either absent, or inaccurate.)
> > make it easy to do the right thing.
> This is where a defined work flow process is vital.
> For various reasons, the workflow used back when Sun was running OOo,
> weren't acceptable here (Apache Foundation running AOo).
> So what happens is that would-be documentation creators sink, due to a
> lack of either clear guidelines, or a pre-defined workflow process.
> ^1: The most commonly encountered such use case, is when different
> audiences have to get different content, but that content differs by
> anything between a word, to three or four paragraphs.
> ^2: For the most commonly encountered use case, LeanPub offers the only
> easy to implement solution that works. The issue with that solution, is
> that one's content is no longer confidential, which is the usual reason
> for having slightly different content for different audiences.
> jonathon


*If you think you can you can, if you think you can't you're right.*

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message