Documentation

xenic
2012-12-31
2013-03-03
  • xenic
    xenic
    2012-12-31

    @kas1e
    The Welcome discussion is growing a little too large so I'm moving the docs discussion to this topic before things get too confused. Here is my last response from the Welcome topic:

    Placing Michaels originals manuals in the files section is fine. I just wanted to preserve them somewhere for reference. Initially, I am trying to produce versions that are formatted as close to the originals as possible. I have the v5.5 manual but will need to refer to his 5.82 PDF to retain the formatting as closely as possible. We don't need the 5.61 manual. It's contents are just suplement to the original 5.5 manual and are repeated in the 5.82 manual. The 5.82 manual is a supplement to the original 5.5 manual and states that only the 5.82 supplement and the 5.5 manual are need for complete documentation of the last Directory Opus 5 release.

    Fixing the original Pagestream 2 files to work in Pagestream 4 is proving to be difficult and time consuming. Therefore I plan to produce edited v5.5 and v5.82 PDF documents which will contain all necessary information for users in the event there is a Dopus5 release before I can combine the documentation into a single PDF. Editing, adding or removing anything from the docs is difficult at this point. Changes on one page can spread to other pages and create a mess. Images will have to wait for now. The PDF is over 250 pages with over 100 images. If we try to have duplicate images for 4 platforms, the PDF will get twice as large and difficult to read. We'll just need to see what is practical.

    The PDF's I plan on making will have bigger pages for online reading. The ogiginal pages (Michael's) are the same size as the original manual and difficult to read on a computer screen. As soon as I have a fairly complete PDF I'll let you check it to see what you think.

     
    Last edit: xenic 2012-12-31
    • kas1e
      kas1e
      2012-12-31

      @Xenic

      If we try to have duplicate images for 4 platforms, the PDF will get twice as large and difficult to read. We'll just need to see what is practical.

      No no, no needs for 4 images all the time, we just will "mix" them, and notice from what platform image is. I.e. in one place image from os4, in another from mos, in another from aros : them all will be the same by logic, just different theme/look. But by this way we will cover all platforms, and docs will be for all the platforms with modern images.

       
      • xenic
        xenic
        2012-12-31

        It shouldn't be too difficult to replace images once I get the original files working right with PageStream4.

         
  • Michael
    Michael
    2012-12-31

    The pages are actually small A5 size (half of normal A4). Theoretically they can be printed as twin pages on A4 using a normal printer. Also if you view the docs in twin page view on 19" screen, you should get the real size view.

    Anybody got scans of original cover, box, floppies, CD ?

    One more thing to note for future manual development, the on-line AmigaGuide help also references to pages in the printed manual, so it's not that simple to re-layout the manual, and probably one of the reasons why Magellan did not get the full manual back then.

     
    • xenic
      xenic
      2012-12-31

      @Michael
      The the original size is good for printing a small manual like the original. Once I get the manuals working with PageStream4, PDF's can be sized for printing and/or online viewing. Thanks for mentioning the AmigaGuide help; that should probably be in the repository since the Help system won't work without the guide. I don't see the guide in the repository yet.

       
  • xenic
    xenic
    2013-01-20

    I finished creating PDF documentation from the PS files and added them to the the Documents directory. The only necessary documentation at this point should be the Dopus 5.5 manual and the Dopus 5.82 update manual that covers all the changes from the DirectoryOpus 5.5. Unless someone else is anxious to add more documentation, I think it will be wise to wait until the opensource code is compiling with GCC. There may need to be changes, removals or additions to the original program which should be included in any "combined" documentation.

    If anyone finds other references to registration, original copyrights or distribution limitations in the PDF documentation, let me know and I'll change it. Otherwise, I'm turning my attention to the sources for now.

     
    • kas1e
      kas1e
      2013-01-21

      Otherwise, I'm turning my attention to the sources for now.

      As seems Jens and Itix busy with all the other stuff, imho we can start for yourself and starting to adapt code for SDI headers.

       
      Last edit: kas1e 2013-01-21
      • xenic
        xenic
        2013-01-21

        I don't have much experience with adapting code to the SDI headers but I'm working on the library files to see if I can get anything working.

         
    • Michael
      Michael
      2013-01-28

      I have a problem viewing your version of the docs in pdf 1.4.
      aPDF gives errors and fails to display pictures.
      AmiPDF looses some of the text.
      Please convert to PDF 1.3 to give access to every Amiga user.

       
      Last edit: Michael 2013-01-28
      Attachments
  • xenic
    xenic
    2013-01-28

    @Michael
    The docs work fine with AmiPDF here. Is your AmiPDF outdated? I'm working on some SDI changes now. I'll have to make some PDF 1.3 versions of the docs and review them to be sure they're O.K. If they are, I'll replace the ones in the repository as soon as I get a chance.

     
  • kas1e
    kas1e
    2013-01-29

    @Xenic
    I assume it is because Michael use some 68k versions of pdf readers, which pretty much dated. If we will have no problems and will loose nothing, then conversion to 1.3 can be ok, but if we will loose something because of such conversion, then my bet that docs should stays on current state, even, if some of users will have no luck to read them on outdated pdf viewers.

    @Michael
    It is 68k readers which you use, or its some dated versios of os4 ones ? (on my current aPDF/os4 everything works fine).

     
  • Michael
    Michael
    2013-01-29

    For AmigaOS 3.x I know only aPDF/PPC v2.2 officially supports PDF 1.3 only, displays text fine, but errors on pictures, wrong encoding format. (source code is available, and it is based on xPDF as the rest are, but no one ever updated it from 2000)
    AmiPDF 68K is supposed to support PDF 1.4 but still has errors and text rendering is wrong as shown on the screenshot. If converted to 1.3 both programs render this docs fine without errors.
    Anyone has a newer AmiPDF in 68k or it has gone aos4ppc only?

     
    Last edit: Michael 2013-01-29
  • xenic
    xenic
    2013-01-29

    @kas1e
    I created PDF 1.3 versions and so far I don't see any problems. I'll look at them more closely before I commit them.

    @Michael
    Give me a couple of days and I will commit PDF 1.3 versions if I don't find any problems with them.

     
  • xenic
    xenic
    2013-02-06

    @Michael & kas1e
    I committed the PDF 1.3 version of the PDF docs. As far as I can tell they work just as well as the PDF 1.4 versions and will hopefully be readable with OS3 PDF readers.

     
  • Michael
    Michael
    2013-02-08

    @xenic
    Have to disappoint you, your build fails under 3.x system. Same problem as 1.4 (missing GFX and letters)
    Tried to reprocess your files and I do get working PDF files that display ok, but I start getting another error - bad colour space for every page.
    Please send me the PGS or PS files for processing.

     
  • xenic
    xenic
    2013-02-09

    @Michael
    I saved the PGS files as PS files and converted them to PDF with the version of GhostScript included in OS4. I specified PDF 1.3 when converting and the PDF headers show PDF 1.3. Are you sure the OS3 PDF readers can even handle PDF 1.3?

    I'll attach the PGS4 files and the PS files to this message. Be warned that the PGS4 files did not convert very well from the original PGS2 files and required a lot of editing and reformatting on my part. As a result, the PGS4 files are inconsistant when it comes to paragraph and font "styles". If you try to edit the PGS4 document files, it is very easy to create errors that proliferate throughout the rest of the document. If you can create good PDF files from the PS files without any editing of the original PGS4 files, that's probably the best approach.

     
    Attachments
  • Michael
    Michael
    2013-02-11

    Bugger. This is not as simple as I hoped it can be!
    The PGS4 PS files are of format Type 3, and they fail to convert to PDF the same way as PGS2 PS files (Type 2).
    Tried PGS5 direct PDF export and that works fine apart from font chaos and small layout glitches as a side effect. Also funny, aPDF displays the files correctly without any error messages, while AmiPDF gives a zillion of errors regarding charset mapping for english!?!

    One thing is clear, for new documentation we have to choose some modern and standard default fonts, this will avoid a lot of problems.

     
    Last edit: Michael 2013-02-11
  • Michael
    Michael
    2013-02-13

    Further experiments show that GS is unable to create a PDF file with a proper object type for images (XObject flag) gives errors.
    The only good route I can think of at the moment is generate a PS file that is acceptable by Adobe Distiller, which can produce proper PDF file, but so far I was unsuccessful to produce a good PS file.
    @xenic - can you export a PS file with other PPD settings (preferably for distiller) ADIST4.PPD or ADIST5.PPD?

     
  • xenic
    xenic
    2013-02-14

    I think the problem is Apdf. I D/L it from Aminet and it won't display any of the PDF's on my hard disk properly. However, I made a ps file with the ADIST5.PPD as you requested and am attaching it to this message. If you get a PDF that works with Apdf, let me know. I don't think there is anything more I can do. All the PDFs I've made work fine with OS4 AmiPDF.

     
    Attachments
  • kas1e
    kas1e
    2013-02-14

    @Xenic,Michael
    I think it will be logical to just make it 1.4/1.3 standard, and forget about it at all, and not loose so much of time on all of this anymore. If os3 version of some PDF readers can't handle it, then we can do nothing about, except that make a new PDF reader for 68k, which is out of our project.

     
    Last edit: kas1e 2013-02-14
  • Michael
    Michael
    2013-02-14

    Got it working!
    There is only one question remaining.
    My original PFS's are much faster to view, and I mean a lot faster!
    I can switch pages every second in aPDF, but with this new build it can take as long as 10 seconds to render a page. I wonder what makes it render so slow.

    Anyway, here is a compatible to everything version of the PDF.

     
    Attachments
  • xenic
    xenic
    2013-02-15

    @Michael
    Good job. Your original PDFs were black&white (no color). Apdf may not be optomized for color. For some reason, saving in color seems to affect pages that only have text as well. In addition, my new PDfs are much lorger than your originals; probably because GhostScript8 adds a lot or extra stuff that just gets in the way. When I was experimenting, I tried GS510 to create the PDF and it completed it in a matter of seconds. GS8 takes 5 minutes to process the same postscript file. It seems that the faster computers get the slower the new code for them gets :-)

    The only reason for updating the PDF docs from your original PDFs was to get rid of the old copyright and registration stuff. It turned out to be a lot of work for very few changes. I think the latest files work for you is because the ADIST5.PPD forced me to save the PS file for a letter size document. Notice that the cover page in your new PDF has white margins on the sides. Thats because the PS file was scaled and printed to letter size (8.5 x 11). We still need a Dopus582 PDF that works with Apdf so I'm attaching Dopus582 files that were procuced in the same way as the working Dopus55 PDF you made. Please see if you can make a Dopus582 PDF that works with Apdf and attach it so I can add both of them to the Documents drawer.

     
    Attachments
  • Michael
    Michael
    2013-02-16

    @xenic It looks like it is a problem of colour depth. Indeed when I have done the originals, I have exported them in greyscale, hoping for smaller file size, since no colours were used in the docs.
    The new PDFs have colour status and require 32bit to render, greyscale PDFs work with just 8bits. So memory transfers are 4 times smaller. It can also be noticed from memory consumption, when aPDF opens the same file (old/new) the new one takes 2MB extra memory.
    As for white borders, they can be cropped, but we will get an odd page size.
    Can you print to PS in A3 size, or it insists on A4?

     
    Attachments
  • xenic
    xenic
    2013-02-16

    @Michael
    Your Dopus582.pdf looks good to me. Should we commit that one for OS3? I printed Dopus55 to A4 instead of letter size and it doesn't have the ugly margins for the cover. I've attached color and greyscale PS files printed to A4. If you can make a good PDF from one of those, attach it to a response and I'll commit it.

     
    Attachments
  • Michael
    Michael
    2013-02-20

    @xenic
    Here is the colour version, the grey version at the moment has no effect apart from making a bigger file! Rendering is still the same slow speed. The only other idea that was not tried is print to A5, not A4. Maybe aPDF internal rendering buffer is allocated dependent on page size, so A4 will take twice the memory of A5 and thus is slower. But it does not have any viewable effect on the screen, display is the same.

     
    Attachments
  • xenic
    xenic
    2013-02-20

    @Michael
    You said I needed to print with ADIST5.PPD so that you could process the PS files with distiller. The ADIST5.PPD doesn't have A5 output. Unless you know of another PPD that works with your distiller, we will just have to use the PDFs you have already made.