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

 
 

You are not allowed to post comments on this tracker with your current authentication level.

bug #56745: Documentation problems in FreeType 2.10.1

Submitter:  Hugh McMaster <hmc>
Submitted:  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:  wl Open/Closed:  Open
Planned Release:  None

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>
Group administrator
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>
Group administrator
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>
Group administrator
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.)

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)
  •  

    There are 5 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

     

    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.13-758e.
    Corresponding source code