PDF documentation

PDF documentation

[Constantine Shulyupin]

Hi,

I have some questions and ideas about documentation in PDF format.
During embedded SW development I often work with documentation,
especially datasheets in PDF format. I have some issues with such
documentation. It is not so easy to manage a lot of PDF documents
sometimes with strange code in file names.  It is not easy to store
and share links to documentation.
It is possible to reference to a PDF page in this way
http://www.ti.com/lit/ds/symlink/omap4430.pdf#page=100 , but it slow
and doesn?t work in all cases.
Sometimes it is more easy just to copy paste and send by email part of
documentation instead of using hyperlinks.
I found, that it is more easy work (and work collaboratively) with
documentation in HTML format. Sometimes it is possible just to convert
PDF to HTML.

Questions:
- have same issues with PDF documentation and datasheets?
- do you think documentation and datasheets in HTML format on a site
can be more useful than PDF?
- what PDF documentation do you use? (You can just drop a link to PDF,
for example http://www.ti.com/lit/ds/symlink/omap4430.pdf)

-- 
Constantine Shulyupin
http://www.MakeLinux.com/
Embedded Linux Systems,
Device Drivers, TI DaVinci

[Celinux-dev] PDF documentation

[Bill Traynor]

On Tue, Oct 16, 2012 at 9:22 AM, Constantine Shulyupin
<const@makelinux.com> wrote:
> Hi,
>
> I have some questions and ideas about documentation in PDF format.
> During embedded SW development I often work with documentation,
> especially datasheets in PDF format. I have some issues with such
> documentation. It is not so easy to manage a lot of PDF documents
> sometimes with strange code in file names.  It is not easy to store
> and share links to documentation.
> It is possible to reference to a PDF page in this way
> http://www.ti.com/lit/ds/symlink/omap4430.pdf#page=100 , but it slow
> and doesn?t work in all cases.
> Sometimes it is more easy just to copy paste and send by email part of
> documentation instead of using hyperlinks.
> I found, that it is more easy work (and work collaboratively) with
> documentation in HTML format. Sometimes it is possible just to convert
> PDF to HTML.
>
> Questions:
> - have same issues with PDF documentation and datasheets?

Yes, PDFs can be unwieldy.  However, for a vendor, they provide an
immutable format that allows vendors to disseminate technical
information in one format, thereby decreasing their documentation
requirements.

> - do you think documentation and datasheets in HTML format on a site
> can be more useful than PDF?

Useful for some perhaps, but not universally useful.  There just isn't
one perfect solution for datasheet documentation.

> - what PDF documentation do you use? (You can just drop a link to PDF,
> for example http://www.ti.com/lit/ds/symlink/omap4430.pdf)

http://beagleboard.org/static/beaglebone/latest/Docs/Hardware/BONE_SCH.pdf

etc. etc.

>
> --
> Constantine Shulyupin
> http://www.MakeLinux.com/
> Embedded Linux Systems,
> Device Drivers, TI DaVinci
> _______________________________________________
> Celinux-dev mailing list
> Celinux-dev at lists.celinuxforum.org
> https://lists.celinuxforum.org/mailman/listinfo/celinux-dev

PDF documentation

[Peter Stuge]

Constantine Shulyupin wrote:
> It is not so easy to manage a lot of PDF documents
> sometimes with strange code in file names.

I tend to rename them in some way that allows me to find them quickly
when I need them.


> It is not easy to store and share links to documentation.

Storing is easy, I just have a pdf folder. Sharing, well, they can be
committed to version control systems and they can be sent via email
or URLs can be shared when it is known that someone will in fact
receive the correct document version by using the URL. URLs are
temporal however, they frequently stop working as vendors re-organize
their web sites.


> Sometimes it is more easy just to copy paste and send by email part
> of documentation instead of using hyperlinks.

A group collaborating around a given hardware certainly needs a
common repository of documentation. A file server is often used
internally. I like to use wikis for public projects. They make it
easy to upload PDF files, references can be made to page
number+section.


> I found, that it is more easy work (and work collaboratively) with
> documentation in HTML format. Sometimes it is possible just to
> convert PDF to HTML.

I strongly prefer working with PDF because it is the canonical
documentation made available by the manufacturer and because my
PDF readers are much much better than my HTML readers.


> - have same issues with PDF documentation and datasheets?

Personally no.


> - do you think documentation and datasheets in HTML format on a
>   site can be more useful than PDF?

Yes and no. I do like detailed information on a web site in the phase
of discovering a new product. Not many vendors provide detailed
technical information on web sites, because the web is so horribly
broken technology, and there are already well-established processes
for producing printed or PDF documentation. Those processes do not
translate 1:1 to web with useful results.

More useful for initial impression, yes, but under no circumstance do
I think HTML would be a good replacement for PDF. Already the fact
that PDF is self-contained but HTML is not should suggest that HTML
is a poor representation outside the web browser, for anything
really.


> - what PDF documentation do you use? (You can just drop a link to PDF,
> for example http://www.ti.com/lit/ds/symlink/omap4430.pdf)

I don't understand what you want to know. I have thousands of data
sheets for parts that I have used, use, or plan to use.


//Peter

PDF documentation

[Constantine Shulyupin]

On Tue, Oct 16, 2012 at 4:05 PM, Peter Stuge <peter@stuge.se> wrote:
> Constantine Shulyupin wrote:
>> - what PDF documentation do you use? (You can just drop a link to PDF,
>> for example http://www.ti.com/lit/ds/symlink/omap4430.pdf)
>
> I don't understand what you want to know. I have thousands of data
> sheets for parts that I have used, use, or plan to use.
> //Peter

Peter, can you please just send me some links to most frequently used
online PDF?
I would like to convert them to html and see how usable it is.

-- 
Constantine Shulyupin
http://www.MakeLinux.com/
Embedded Linux Systems,
Device Drivers, TI DaVinci

PDF documentation

[Peter Stuge]

Constantine Shulyupin wrote:
> >> - what PDF documentation do you use? (You can just drop a link to PDF,
> >> for example http://www.ti.com/lit/ds/symlink/omap4430.pdf)
> >
> > I don't understand what you want to know. I have thousands of data
> > sheets for parts that I have used, use, or plan to use.
> 
> Peter, can you please just send me some links to most frequently
> used online PDF?

I don't have a particular PDF that is used more frequently than
others. Here's one I used recently, for a common flash chip:

http://www.macronix.com/QuickPlace/hq/PageLibrary4825740B00298A3B.nsf/h_Index/DBACA1C90564EBB248257639003A563A/$File/MX29GL128E,%203V%20(VI-O),%20128Mb,%20v1.5.pdf


> I would like to convert them to html and see how usable it is.

As others also mention I think that is backwards. If you want to do
something good for documentation then look for workflows where a
single source format allows to perfectly generate a variety of output
formats.

Perfectly matters. Anyone can cobble up a script to render characters
on a PDF page. It will look awful, which distracts readers, which
generates more support inquiries.

PDF is a digital sheet media. HTML comes nowhere near the tools
PDF offers for typesetting and typography. PDFs can be made beautiful
without a lot of effort.

Creating beautiful HTML is, let's say, uneconomical. Let's not talk
about how it limits the designer. (That's what really good web
designers do - know those limits yet still create working UX.)

Check out PostScript and then check out HTML. The similarities may be
comparable to those of a magnificent fil?t knife and a wooden spoon.

One can of course prepare food with both.


As I mentioned before, I still find HTML superior for discovery and
early selection of new products. It is unneccessarily and
unpleasantly time-consuming to deal with PDF documents if there is a
particular requirement which needs to be checked against a large
number of available products. I was looking for a low-profile SMD
pushbutton recently, and in order to find the information I needed I
had to view a lot of PDFs at many manufacturers. One manufacturer
however had the information *right there* on the product family web
page. That saved me a lot of time, and I chose one of their products.


//Peter

PDF documentation

[Constantine Shulyupin]

On Wed, Oct 17, 2012 at 6:51 PM, Peter Stuge <peter@stuge.se> wrote:
> Constantine Shulyupin wrote:
>> Peter, can you please just send me some links to most frequently
>> used online PDF?
>
> I don't have a particular PDF that is used more frequently than
> others. Here's one I used recently, for a common flash chip:
>
> http://www.macronix.com/QuickPlace/hq/PageLibrary4825740B00298A3B.nsf/h_Index/DBACA1C90564EBB248257639003A563A/$File/MX29GL128E,%203V%20(VI-O),%20128Mb,%20v1.5.pdf
>
>> I would like to convert them to html and see how usable it is.

I've converted you pdf and uploaded to a site:
http://makelinux.net/lib/macronix/MX29GL128E/

It can't even approach to replase PDF,  but it adds possibility to
send in a e-mail link to a specific page:
COMMON FLASH MEMORY INTERFACE (CFI) MODE:
http://makelinux.net/lib/macronix/MX29GL128E/doc-34
http://makelinux.net/lib/macronix/MX29GL128E/doc-35

Here is jet another document, huge 5K pages DS of OMAP4460:
http://makelinux.net/lib/ti/OMAP4460/
http://makelinux.net/lib/ti/OMAP4460/doc-outline
OMAP4460 USBPHY Registers: http://makelinux.net/lib/ti/OMAP4460/doc-5464
Debug Modules Memory Mapping: http://makelinux.net/lib/ti/OMAP4460/doc-5845

How it looks?
Can it be useful?

-- 
Constantine Shulyupin
http://www.MakeLinux.com/
Embedded Linux Systems,
Device Drivers, TI DaVinci

[Celinux-dev] PDF documentation

[Tim Bird]

On 10/17/2012 12:26 PM, Constantine Shulyupin wrote:
> On Wed, Oct 17, 2012 at 6:51 PM, Peter Stuge <peter@stuge.se> wrote:
>> Constantine Shulyupin wrote:
>>> Peter, can you please just send me some links to most frequently
>>> used online PDF?
>>
>> I don't have a particular PDF that is used more frequently than
>> others. Here's one I used recently, for a common flash chip:
>>
>> http://www.macronix.com/QuickPlace/hq/PageLibrary4825740B00298A3B.nsf/h_Index/DBACA1C90564EBB248257639003A563A/$File/MX29GL128E,%203V%20(VI-O),%20128Mb,%20v1.5.pdf
>>
>>> I would like to convert them to html and see how usable it is.
> 
> I've converted you pdf and uploaded to a site:
> http://makelinux.net/lib/macronix/MX29GL128E/
> 
> It can't even approach to replase PDF,  but it adds possibility to
> send in a e-mail link to a specific page:
> COMMON FLASH MEMORY INTERFACE (CFI) MODE:
> http://makelinux.net/lib/macronix/MX29GL128E/doc-34
> http://makelinux.net/lib/macronix/MX29GL128E/doc-35

Being able to reference an individual page, table or section of a PDF
with a click would indeed be a nice feature.

Being able to identify a page of an existing online PDF is already
possible with URLs.  See
http://stackoverflow.com/questions/125632/is-it-possible-to-link-to-a-bookmark-within-a-pdf-using-url-parameters

So, the following would get you to page 34, in the original PDF:
http://www.macronix.com/QuickPlace/hq/PageLibrary4825740B00298A3B.nsf/h_Index/DBACA1C90564EBB248257639003A563A/$File/MX29GL128E,%203V%20(VI-O),%20128Mb,%20v1.5.pdf#page=34

> Here is jet another document, huge 5K pages DS of OMAP4460:
> http://makelinux.net/lib/ti/OMAP4460/
> http://makelinux.net/lib/ti/OMAP4460/doc-outline
> OMAP4460 USBPHY Registers: http://makelinux.net/lib/ti/OMAP4460/doc-5464
> Debug Modules Memory Mapping: http://makelinux.net/lib/ti/OMAP4460/doc-5845
> 
> How it looks?
> Can it be useful?

Careful there.  These documents are copyright.  Even though the OMAP4460 document
says it is "public", I'm not sure it's legal to post verbatim contents to a web site.

So - useful or not, I'm worried it's not legal.
 -- Tim

=============================
Tim Bird
Architecture Group Chair, CE Workgroup of the Linux Foundation
Senior Staff Engineer, Sony Network Entertainment
=============================

[Celinux-dev] PDF documentation

[Constantine Shulyupin]

On Thu, Oct 18, 2012 at 12:04 AM, Tim Bird <tim.bird@am.sony.com> wrote:
> Being able to identify a page of an existing online PDF is already
> possible with URLs.  See
> http://stackoverflow.com/questions/125632/is-it-possible-to-link-to-a-bookmark-within-a-pdf-using-url-parameters
Yes, I know. I already wrote about it the fist e-mail. It is not
applicable in all cases.

> So, the following would get you to page 34, in the original PDF:
> http://www.macronix.com/QuickPlace/hq/PageLibrary4825740B00298A3B.nsf/h_Index/DBACA1C90564EBB248257639003A563A/$File/MX29GL128E,%203V%20(VI-O),%20128Mb,%20v1.5.pdf#page=34

Yes, it works when pdf is hosted properly (not forced for download),
not archived and relatively small.
This method will not work with
http://focus.ti.com/pdfs/wtbu/OMAP4460_ES1.x_PUBLIC_TRM_vI.zip

Even unzipped pdf is 23 MB - too heavy for online browning.

> Careful there.  These documents are copyright.  Even though the OMAP4460 document
> says it is "public", I'm not sure it's legal to post verbatim contents to a web site.
>
> So - useful or not, I'm worried it's not legal.
>  -- Tim

Quote:

Reproduction of significant portions of TI information in TI data
books or data sheets is permissible only if reproduction is without
alteration and is accompanied by all associated warranties,
conditions, limitations, and notices.

from http://makelinux.net/lib/ti/OMAP4460/doc-5864

Thank you, Tim.

>
> =============================
> Tim Bird
> Architecture Group Chair, CE Workgroup of the Linux Foundation
> Senior Staff Engineer, Sony Network Entertainment
> =============================
>



-- 
Constantine Shulyupin
http://www.MakeLinux.com/
Embedded Linux Systems,
Device Drivers, TI DaVinci

PDF documentation

[Russell King - ARM Linux]

On Tue, Oct 16, 2012 at 04:05:55PM +0200, Peter Stuge wrote:
> > Sometimes it is more easy just to copy paste and send by email part
> > of documentation instead of using hyperlinks.
> 
> A group collaborating around a given hardware certainly needs a
> common repository of documentation. A file server is often used
> internally. I like to use wikis for public projects. They make it
> easy to upload PDF files, references can be made to page
> number+section.

This actually depends.  You have to be careful of copyright infringement.
Generally, you are allowed to download and store one copy of the
documentation for your own personal use and not redistribute it.  Whether
it says for personal use or not is another gotcha there.

Most places have fair use allowed in law, which means that the copy and
paste of limited extracts is permitted - but in this day and age of global
networks, you have to be really careful because your local law may not
be the applicable law.

> > I found, that it is more easy work (and work collaboratively) with
> > documentation in HTML format. Sometimes it is possible just to
> > convert PDF to HTML.
> 
> I strongly prefer working with PDF because it is the canonical
> documentation made available by the manufacturer and because my
> PDF readers are much much better than my HTML readers.

Again, copyright may be an issue with this kind of approach, because
you're technically redistributing someone elses work.  You need to
check what you're permitted to do with each document before you do it,
and if you aren't permitted to redistribute it, seek permission from the
copyright owner.

I'm not sure how the various datasheet sites get around this, but I
suspect they may have negotiated blanket permissions with most of the
silicon manufacturers, espsecially as some modify the PDFs adding
a final page to them.

> More useful for initial impression, yes, but under no circumstance do
> I think HTML would be a good replacement for PDF. Already the fact
> that PDF is self-contained but HTML is not should suggest that HTML
> is a poor representation outside the web browser, for anything
> really.

The big problem with anything online is that you must be online to access
it.  If your connection to the Internet goes down, you lose access to
that information.  If the site hosting it goes down, same problem...


(In the old days of databooks, companies used to either be given the
databook by the sales rep, or -rarely- they bought the databook, and
the book sat in the companies library... and any employee could make
use of that single copy...)

PDF documentation

[Peter Stuge]

Russell King - ARM Linux wrote:
> You have to be careful of copyright infringement.

Yeah, because a company might sue for datasheet copyright
infringement when someone is (if only potentially) buying
their product.

I would think that one through one more time. :)


//Peter

PDF documentation

[Russell King - ARM Linux]

On Thu, Oct 18, 2012 at 12:25:20AM +0200, Peter Stuge wrote:
> Russell King - ARM Linux wrote:
> > You have to be careful of copyright infringement.
> 
> Yeah, because a company might sue for datasheet copyright
> infringement when someone is (if only potentially) buying
> their product.
> 
> I would think that one through one more time. :)

No, I did.  You take a copy of the data sheet and republish it publically.
Take a moment to think about that...

Consider also, from their point of view, the issue of documentation
control.  Notice that most companies don't provide download links for
old documentation...

If there was not a problem here, all documentation would explicitly
state that it is able to be freely distributed.  However, this is not
the case.  Maybe you should read the legal status of documentation from
ARM?  It explicitly states that you are not permitted to redistribute
it... why put that in if you don't mean it?

PDF documentation

[Peter Stuge]

Russell King - ARM Linux wrote:
> If there was not a problem here, all documentation would explicitly
> state that it is able to be freely distributed.

Lawyers like job security as much as the guy on the floor, theirs
just involves different psychology.


//Peter

[Celinux-dev] PDF documentation

[Geert Uytterhoeven]

On Thu, Oct 18, 2012 at 12:29 AM, Russell King - ARM Linux
<linux@arm.linux.org.uk> wrote:
> Consider also, from their point of view, the issue of documentation
> control.  Notice that most companies don't provide download links for
> old documentation...

Yep. That's why I archive all datasheets I can get my hands on. They will
disappear from the web.

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert at linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

[Celinux-dev] PDF documentation

[Wolfgang Denk]

Dear Constantine Shulyupin,

In message <CAE7jHC83biZy7TNYSr+-X85tpenqtAHuwSO47Q-6+XRF0fUxLA@mail.gmail.com> you wrote:
> 
> I have some questions and ideas about documentation in PDF format.
> During embedded SW development I often work with documentation,
> especially datasheets in PDF format. I have some issues with such
> documentation. It is not so easy to manage a lot of PDF documents
> sometimes with strange code in file names.  It is not easy to store
> and share links to documentation.

PDF has a lot of advantages in many situations, but I agree that it is
also non-perfect for many other use cases.

> Questions:
> - have same issues with PDF documentation and datasheets?
> - do you think documentation and datasheets in HTML format on a site
> can be more useful than PDF?

HTML is really useful in a web browser only.

For documentation of the U-Boot boot loader we use a very different
approach:  documentation is created, stored and edited in a wiki
(using FosWiki, see http://foswiki.org/).  This has the advantage that
you can make it either easily editable to the community, or put
arbitrary access restrictions to it by using wiki user / group access
permissions.  In combination with some plugins (like TocPlugin,
BookmakerPlugin and PublishPlugin) we can then "linearize" the entries
in the wiki to generate a "book" which can be read both online (as
HTML) or offline (by publishing the content as a linerarized, single
HTLP, plain text, PDF and/or PostScript document).

To give you a feeling how this works, please see for example 
	http://www.denx.de/wiki/view/DULG/Manual?stickboard=m28
	http://www.denx.de/wiki/publish/DULG/DULG-m28.html
	http://www.denx.de/wiki/publish/DULG/DULG-m28.ps
and	http://www.denx.de/wiki/publish/DULG/DULG-m28.pdf

[Actually this documentation does much more behind the scenes; all
examples in this documentation come from include files which are
automatically generated from our regression test suite (DUTS); so the
procedure is to come up with a new software version, run the test
suite over it, upload the generated log files to the web server, and
voila, there is a new version of the documentation matching exactly
the new software version.]

And the nice thing is: all this is based on free software only...

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
One difference between a man and a machine is that a machine is quiet
when well oiled.

[Celinux-dev] PDF documentation

[Tim Bird]

On 10/16/2012 07:35 AM, Wolfgang Denk wrote:
> Dear Constantine Shulyupin,
> 
> In message <CAE7jHC83biZy7TNYSr+-X85tpenqtAHuwSO47Q-6+XRF0fUxLA@mail.gmail.com> you wrote:
>>
>> I have some questions and ideas about documentation in PDF format.
>> During embedded SW development I often work with documentation,
>> especially datasheets in PDF format. I have some issues with such
>> documentation. It is not so easy to manage a lot of PDF documents
>> sometimes with strange code in file names.  It is not easy to store
>> and share links to documentation.
> 
> PDF has a lot of advantages in many situations, but I agree that it is
> also non-perfect for many other use cases.
> 
>> Questions:
>> - have same issues with PDF documentation and datasheets?
>> - do you think documentation and datasheets in HTML format on a site
>> can be more useful than PDF?
> 
> HTML is really useful in a web browser only.

I agree.  This has already been covered by others, but HTML
consists of multiple files, and so is not convenient to store
or transmit atomically.  Also, HTML is often difficult to print
(you have to explicitly remove the page decorations added by
the site (or find the 'print' option on the page).

> For documentation of the U-Boot boot loader we use a very different
> approach:  documentation is created, stored and edited in a wiki
> (using FosWiki, see http://foswiki.org/).  This has the advantage that
> you can make it either easily editable to the community, or put
> arbitrary access restrictions to it by using wiki user / group access
> permissions.  In combination with some plugins (like TocPlugin,
> BookmakerPlugin and PublishPlugin) we can then "linearize" the entries
> in the wiki to generate a "book" which can be read both online (as
> HTML) or offline (by publishing the content as a linerarized, single
> HTLP, plain text, PDF and/or PostScript document).
> 
> To give you a feeling how this works, please see for example 
> 	http://www.denx.de/wiki/view/DULG/Manual?stickboard=m28
> 	http://www.denx.de/wiki/publish/DULG/DULG-m28.html
> 	http://www.denx.de/wiki/publish/DULG/DULG-m28.ps
> and	http://www.denx.de/wiki/publish/DULG/DULG-m28.pdf
...
> And the nice thing is: all this is based on free software only...

This is really interesting.

Several years ago, CELF tried to add a similar capability to
MoinMoin (the ability to take arbitrary page lists, and
automatically publish them to PDF).  Unfortunately, it didn't
work very well.  The tools to produce PDF were pretty bad back then.

I think the wiki approach is very good for collecting the
information, and having a way to snapshot and publish the items
solves some of the problems wikis have (uneven editing across
multiple pages over time can lead to inconsistent pages).

It sounds like the tools have improved since we did this, and
maybe we should look again and see if there's something similar
we could add to the elinux wiki.
 -- Tim

=============================
Tim Bird
Architecture Group Chair, CE Workgroup of the Linux Foundation
Senior Staff Engineer, Sony Network Entertainment
=============================

[Celinux-dev] PDF documentation

[Wolfgang Denk]

Dear Tim,

In message <507DA84A.2080904@am.sony.com> you wrote:
>
> Several years ago, CELF tried to add a similar capability to
> MoinMoin (the ability to take arbitrary page lists, and
> automatically publish them to PDF).  Unfortunately, it didn't
> work very well.  The tools to produce PDF were pretty bad back then.

We use Foswiki for capabilities like this.  Note that I definitely
don't want to start a "my wiki is better than your wiki" religous war
here ;-)

> It sounds like the tools have improved since we did this, and
> maybe we should look again and see if there's something similar
> we could add to the elinux wiki.

You are using mediawiki - there appear to be such solutions as well,
see for example
http://www.blue-spice.org/de/produkte/packages/bookmaker/
Sorry, this is in German only, and no free software.

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
"He only drinks when he gets depressed." "Why does he get depressed?"
"Sometimes it's because he hasn't had a drink."
                                     - Terry Pratchett, _Men at Arms_

[Celinux-dev] PDF documentation

[shiraz hashim]

Dear Wolfgang,

On Wed, Oct 17, 2012 at 3:42 PM, Wolfgang Denk <wd@denx.de> wrote:
> We use Foswiki for capabilities like this.  Note that I definitely
> don't want to start a "my wiki is better than your wiki" religous war
> here ;-)

I like documentation maintained on denx site. However, have you tried
light markup language like asciidoc for documentation.

The good thing is that it is powerful enough to convert into docbook and
then onto pdf, html or other formats, at the same time clean enough to
be readable in txt format itself.

The text base provides an opportunity to use git or other version tools and
apply same worklow as that of code development.

-- 
regards
Shiraz Hashim

PDF documentation

[Mikael Pettersson]

On Tue, 16 Oct 2012 15:22:52 +0200, Constantine Shulyupin <const@makelinux.com> wrote:
> Hi,
> 
> I have some questions and ideas about documentation in PDF format.
> During embedded SW development I often work with documentation,
> especially datasheets in PDF format. I have some issues with such
> documentation. It is not so easy to manage a lot of PDF documents
> sometimes with strange code in file names.  It is not easy to store
> and share links to documentation.
> It is possible to reference to a PDF page in this way
> http://www.ti.com/lit/ds/symlink/omap4430.pdf#page=3D100 , but it slow
> and doesn't work in all cases.
> Sometimes it is more easy just to copy paste and send by email part of
> documentation instead of using hyperlinks.
> I found, that it is more easy work (and work collaboratively) with
> documentation in HTML format. Sometimes it is possible just to convert
> PDF to HTML.
> 
> Questions:
> - have same issues with PDF documentation and datasheets?

No. They work just fine.

> - do you think documentation and datasheets in HTML format on a site
> can be more useful than PDF?

Fore brief overviews, html will do, but for actual technical documentation
PDF is *infinitely* better than html.

> - what PDF documentation do you use? (You can just drop a link to PDF,
> for example http://www.ti.com/lit/ds/symlink/omap4430.pdf)

CPU manuals and errata updates, ISA manuals, ABI manuals.

PDF documentation

[Alexander Holler]

Am 16.10.2012 15:22, schrieb Constantine Shulyupin:

> Questions:
> - have same issues with PDF documentation and datasheets?

No.

> - do you think documentation and datasheets in HTML format on a site
> can be more useful than PDF?

I would prefer if the source for the (PDF-)documentation would be
available in some open, free and widely used meta-language, e.g. LaTeX
(or XML or txt2tags or ..., but I'm oldschool and prefer LaTeX ;) ). So
everyone could build it's copy in whatever format he prefers or needs.

Regards,

Alexander

PDF documentation

[Jon Loeliger]

> 
> I would prefer if the source for the (PDF-)documentation would be
> available in some open, free and widely used meta-language, e.g. LaTeX
> (or XML or txt2tags or ..., but I'm oldschool and prefer LaTeX ;) ). So
> everyone could build it's copy in whatever format he prefers or needs.

Perhaps DocBook?  It is readily rendered as PDF or HTML.

jdl

PDF documentation

[Grant Edwards]

On 2012-10-18, Jon Loeliger <jdl@jdl.com> wrote:
>> 
>> I would prefer if the source for the (PDF-)documentation would be
>> available in some open, free and widely used meta-language, e.g. LaTeX
>> (or XML or txt2tags or ..., but I'm oldschool and prefer LaTeX ;) ). So
>> everyone could build it's copy in whatever format he prefers or needs.
>
> Perhaps DocBook?  It is readily rendered as PDF or HTML.

Unfortunately DocBook can't be read/edited by a human.  IMO, Docbook
is only suitable as a machine-generated intermediate format.

I'd recommend one of the lightweight markup languages like asciidoc or
reStructuredText.  They're easy to read/write, perfectly usable in the
source form and can be rendered into PDF, HTML, ODT, DocBook, whatever.

-- 
Grant Edwards               grant.b.edwards        Yow! Don't SANFORIZE me!!
                                  at               
                              gmail.com