Date
1 - 19 of 19
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 |
|
|
|
Bill Traynor <wmat@...>
On Tue, Oct 16, 2012 at 9:22 AM, Constantine Shulyupin
<const@...> wrote: Hi,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 siteUseful 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,http://beagleboard.org/static/beaglebone/latest/Docs/Hardware/BONE_SCH.pdf etc. etc.
|
|
|
|
Wolfgang Denk
Dear Constantine Shulyupin,
In message <CAE7jHC83biZy7TNYSr+-X85tpenqtAHuwSO47Q-6+XRF0fUxLA@...> you wrote: PDF has a lot of advantages in many situations, but I agree that it is also non-perfect for many other use cases. Questions: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@... One difference between a man and a machine is that a machine is quiet when well oiled. |
|
|
|
Tim Bird <tim.bird@...>
On 10/16/2012 07:35 AM, Wolfgang Denk wrote:
Dear Constantine Shulyupin,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... 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 ============================= |
|
|
|
Wolfgang Denk
Dear Tim,
In message <507DA84A.2080904@...> you 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 ;-) It sounds like the tools have improved since we did this, andYou 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@... "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_ |
|
|
|
Constantine Shulyupin
On Tue, Oct 16, 2012 at 4:05 PM, Peter Stuge <peter@...> wrote:
Constantine Shulyupin wrote:Peter, can you please just send me some links to most frequently used- what PDF documentation do you use? (You can just drop a link to PDF,I don't understand what you want to know. I have thousands of data 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 |
|
|
|
shiraz hashim <shiraz.linux.kernel@...>
Dear Wolfgang,
On Wed, Oct 17, 2012 at 3:42 PM, Wolfgang Denk <wd@...> wrote: We use Foswiki for capabilities like this. Note that I definitelyI 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 |
|
|
|
Peter Stuge <peter@...>
Constantine Shulyupin wrote:
I don't have a particular PDF that is used more frequently thanPeter, can you please just send me some links to most frequently- what PDF documentation do you use? (You can just drop a link to PDF,I don't understand what you want to know. I have thousands of data 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 |
|
|
|
Constantine Shulyupin
On Wed, Oct 17, 2012 at 6:51 PM, Peter Stuge <peter@...> wrote:
Constantine Shulyupin wrote:I've converted you pdf and uploaded to a site:Peter, can you please just send me some links to most frequentlyI don't have a particular PDF that is used more frequently than 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 |
|
|
|
Tim Bird <tim.bird@...>
On 10/17/2012 12:26 PM, Constantine Shulyupin wrote:
On Wed, Oct 17, 2012 at 6:51 PM, Peter Stuge <peter@...> wrote:Being able to reference an individual page, table or section of a PDFConstantine Shulyupin wrote:I've converted you pdf and uploaded to a site:Peter, can you please just send me some links to most frequentlyI don't have a particular PDF that is used more frequently than 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: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 ============================= |
|
|
|
Russell King - ARM Linux <linux@...>
On Tue, Oct 16, 2012 at 04:05:55PM +0200, Peter Stuge wrote:
This actually depends. You have to be careful of copyright infringement.Sometimes it is more easy just to copy paste and send by email partA group collaborating around a given hardware certainly needs a 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. Again, copyright may be an issue with this kind of approach, becauseI found, that it is more easy work (and work collaboratively) withI strongly prefer working with PDF because it is the canonical 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 doThe 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...) |
|
|
|
Peter Stuge <peter@...>
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 |
|
|
|
Constantine Shulyupin
On Thu, Oct 18, 2012 at 12:04 AM, Tim Bird <tim.bird@...> wrote:
Being able to identify a page of an existing online PDF is alreadyYes, 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: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 documentQuote: 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.
-- Constantine Shulyupin http://www.MakeLinux.com/ Embedded Linux Systems, Device Drivers, TI DaVinci |
|
|
|
Russell King - ARM Linux <linux@...>
On Thu, Oct 18, 2012 at 12:25:20AM +0200, Peter Stuge wrote:
Russell King - ARM Linux wrote:No, I did. You take a copy of the data sheet and republish it publically.You have to be careful of copyright infringement.Yeah, because a company might sue for datasheet copyright 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? |
|
|
|
Peter Stuge <peter@...>
Russell King - ARM Linux wrote:
If there was not a problem here, all documentation would explicitlyLawyers like job security as much as the guy on the floor, theirs just involves different psychology. //Peter |
|
|
|
Geert Uytterhoeven
On Thu, Oct 18, 2012 at 12:29 AM, Russell King - ARM Linux
<linux@...> wrote: Consider also, from their point of view, the issue of documentationYep. 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@... 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 |
|
|
|
Alexander Holler <holler@...>
Am 16.10.2012 15:22, schrieb Constantine Shulyupin:
Questions:No. - do you think documentation and datasheets in HTML format on a siteI 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 |
|
|
|
Jon Loeliger <jdl@...>
Perhaps DocBook? It is readily rendered as PDF or HTML. jdl |
|
|
|
Grant Edwards <grant.b.edwards@...>
On 2012-10-18, Jon Loeliger <jdl@...> wrote:
Unfortunately DocBook can't be read/edited by a human. IMO, DocbookPerhaps DocBook? It is readily rendered as PDF or HTML. 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 |
|
|