bugThe FreeType Project - Bugs: bug #56745, Documentation problems in FreeType...

 
 

bug #56745: Documentation problems in FreeType 2.10.1

Submitted by:  Hugh McMaster <hmc>
Submitted on:  Sun 11 Aug 2019 12:50:04 PM UTC  
Votes:  5  
 
Severity:  3 - Normal Item Group:  Incorrect behaviour
Status:  In Progress Privacy:  Public
Assigned to:  Werner LEMBERG <wl> Open/Closed:  Open
Planned Release:  None

Add a New Comment (Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

( Jump to the original submission)

Sat 21 Dec 2019 10:17:25 PM UTC, comment #7: 

Patches from

  https://savannah.nongnu.org/patch/?9879

have been applied.

Werner LEMBERG <wl>
Project AdministratorIn charge of this item.
Sun 15 Sep 2019 12:51:40 PM UTC, comment #6: 

1(a): This looks like a packaging error in FreeType that has existed for a long time.

2(a),(b),(c): These require a patch in FreeType (to come) and also a patch in the related docwriter project. I've sent a pull request (https://github.com/freetype/docwriter/pull/26).

2(d),(e),(f): These are being fixed upstream.

Hugh McMaster <hmc>
Tue 20 Aug 2019 01:13:42 PM UTC, comment #5: 

My only reason is that freetype-doc only contains a small amount of additional documentation. I tend to think of a documentation package as containing all documentation (the Debian package combines it all into one).

That said, there are many good reasons to keep the auxiliary documentation separate, so let's keep it like that.

Hugh McMaster <hmc>
Tue 20 Aug 2019 12:25:03 PM UTC, comment #4: 

Hmm, this would be quite unusual.  Normally, small libraries come with documentation in the source tarball; the stuff in the `freetype-doc' bundle is something additional and thus not essential.

I could imagine the opposite way, namely to merge the `freetype-doc' stuff into the main bundle.  However, this blows up the library bundle size by almost 100%...

Why do you want the API reference in `freetype-doc'?

Werner LEMBERG <wl>
Project AdministratorIn charge of this item.
Tue 20 Aug 2019 11:58:20 AM UTC, comment #3: 

Hi Werner, I'll see what I can do to help.

Are you open to moving the API reference from the main source tarballs to the freetype-doc tarballs? I think that could work quite nicely by keeping all documentation together for ease of access.

Hugh McMaster <hmc>
Tue 20 Aug 2019 11:19:46 AM UTC, comment #2: 

Thanks a lot for your report.  Unfortunately, I won't have time in the next few weeks to work on this.  Could you help and provide patches?

Werner LEMBERG <wl>
Project AdministratorIn charge of this item.
Sun 11 Aug 2019 01:40:23 PM UTC, comment #1: 

In fact, all Javascript files in the documentation are minified, but their file names do not indicate this (which they should).

Lunr.js is in the Application.<commit>.js file (again minified). The top half of the file appears to have been copied from some other source, but is minified and has no attribution. Lunr.js should probably be a separate file.

All of these points cause problems for Debian and its derivatives.

Hugh McMaster <hmc>
Sun 11 Aug 2019 12:50:04 PM UTC, original submission:  

While preparing FreeType 2.10.1 for release in Debian, I have noticed several problems in the documentation.

1. freetype-doc
(a) In docs/documentation.html, rasterinfo.html is missing.

(b) The hyperlink to the API Reference is broken.

2. API Reference
(a) This documentation is created in the 'reference/site' sub-directory, which is inconsistent with the other sub-topics, such as 'design', 'glyphs' and 'tutorial'. The hyperlink in docs/index.html (see 1(b) above) actually points to the correct place; unfortunately, the index.html is not located in the directory.

(b) index.html is located in the same directory as ft2-index.html and the relative HTML files. This is incorrect. It appears index.html should be located in 'reference' only. In the breadcrumb navigation ("FreeType >> Docs >> Table of Contents"), the 'Docs' hyperlink points back to the 'reference' parent directory. Unfortunately, as index.html is missing, only the directory structure is displayed.

(c) There is no reason to have the API Reference located in 'reference/site'.

(d) FontAwesome files are generated and shipped, but are unused.

(e) Lunr JS files are shipped, but are without source attribution.

(f) Lunr Language files are shipped, but are minified without '.min' appearing in the file names. Also, there is no source attribution.

Hugh McMaster <hmc>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by mathstuf (Voted in favor of this item)
  • -email is unavailable- added by wl (Posted a comment)
  • -email is unavailable- added by hmc (Submitted the item)
  •  

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 5 encouragements so far.

    Only logged-in users can vote.

     

     

     

    Follow 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2019-12-21 wl StatusNone => In Progress
        Assigned toNone => wl
    2019-11-12 mathstuf Carbon-Copy- => Added mathstuf

    Back to the top


    Powered by Savane 3.5