Skip to content

TODO

Jump to bottom
Takuto ASAKURA edited this page Jan 7, 2019 · 8 revisions

Finding documents outside TeX Live

Currently, Texdoc has only limitted feature to access documents outside Texdoc; it is able to find documents in TEXDOCS but it is not perfect. Some discussions related to this problem are in issue #17, so if you have any idea or suggestion, please leave comments there.

Followings are some concrete plans:

Alias variant (alias*)

A variety of alias to specify absolute path. Possible syntax in texdoc.cnf:

alias* foo = /path/to/your/foobar.pdf

This feature will allow users to access documents which they want to open via Texdoc, but cannot find the right position for it in a TEXMF tree. It will also be helpful to make the standard configuration to point some document which have "general" name like README (see #36).

Getting documents from CTAN mirrors

Some TeX Live users install TeX Live without documentation. For those users, current Texdoc is useless at all.

Then, how about implementing a feature to download a document on demand if the document does not exist in the local TEXMFs? I first thought that this is meaningless because it requires the Internet connection; thus, it is far better for the users who can always use (good) newtworks to search with Google (or whatever). But if we cache the document once downloaded, doesn't it make the feature useful?

The problem here is that the versions of the documents and those of the actual packages installed in the local TEXMFs could be different. Can we ignore that difference?

Debug outputs reproducibility

Texdoc has limited reproducibility for its debug outputs. This is basically due to the specification of Lua's tables (the order of table items are not stable at all). This could possibly make it difficult to debug Texdoc (well, our test scripts in the spec directory are doing fine under this specification at this point).

It is possible to make the output stable by sorting internal tables. However, sorting in lexicographical order is not essential for Texdoc function (i.e., searching, scoring, and determining which documents to show) and it is not worth spending time and caluculation resources just for making debug output stable (because only a tiny few people in the world debugs Texdoc).

We should address this problem by using ordered data structure for storing document lists (again, it don't have to be in lexicographical order. All we need is order-stable data structure). This solution is ideal because it will not add unnecessary calculation process.

cf. issue #24

Scoring overhaul

Good package (either from the tlpdb or directory name) should be much more important for scoring. E.g.

  • With texdoc article
    • spie/article.pdf should never get such a high score
  • With texdoc todo
    • todo/todo-spl.pdf should win over todonotes/todonotes.pdf
  • With texdoc ean
    • ean/Readme should win over barcodes/eandoc (probably)
  • With texdoc bxtexlogo
    • bxtexlogo-sample.pdf is not necessary to be the best
    • but also it should not be judged as "bad" (get score <0)

Files found using the tlpdb only should be scored heuristically as if <pkgname> were asked for. Make sure heuristic scoring returns a higher score for names actually containing the string. (Check the result with psnfss2e aliases.)

See aliases marked XXX in texdoc.cnf.

Using tlpdb

There are some ideas to make this better:

  • Using texlive/tlpdb.tlu for tlpdb reading
  • Make the parsing faster so that the no cache file is needed

Documentation (texdoc.pdf) readability

The documentation of Texdoc (namely, texdoc.pdf) is desined by the former maintainer (mpg). Respecting that fact, we keep the design for now, but some people might think it is not so much readable (e.g., is it suitable to use a sans-selif font for the text?).

We know that it is extremely difficult to make a design which is agreed by all people in the world (and in addition to that, I am not a professional designer), so it will take a while to change the desing of the document, but still we should try to make the document more redable for many people.

Misc

  • Add complehensive test scripts
  • Make the list of good and/or bad comments from the catalogue configurable?
    • Currently, "readme" is only hard-coded as "bad"
    • e.g. "package documentation" might get a bonus
  • Provide interfaces for Plug-ins?
    • cf. Some people want to search document by macro name
  • Try to guess which *.tex files are examples and allow them?

Notes by former maintainer (mpg)

New options
-----------

--html-lists options: output the lists as html (à la mthelp)

--index-by-topic: build on the fly a local version of the catalogue's
bytopic.html page (see also --apropos)


Not sure about that
-------------------

Information from the tlpdb isn't always as up-to-date as the catalogue, in case
the catalogue has been fixed for a package that wasn't update. Should I generate
Data.meta.lua directly from a fresh catalogue version?
    For now, just force update of the packages in TL when I notice.

Try guessin lang from file name when there is no info in the catalogue?

What to do with tools/coverage? May want to discuss this with Phlipp S.

tlpdb cache should check if ext_list has changed, in theory.
    Is it worth it in practice? I'll do it if someone complains...

BUG: finds non-existing files in tl2010 (probably from another tlpdb?)
ex: texdoc luasseq on my machine while tl10 is active
    Ok, got it: tlpdb cache is not invalidated when switching to an older
    tlpdb files from the same release. I wonder if it's worth fixing.

Caching: now used only for tlpdb. Is it worth using it for ls-R files?
Configuration files?

Add support for shell-style globs (standard regex is probably too hard)
    Well, would anyone really use it? (would be for patterns in texdoc.cnf, not
    for texdoc arguments)

Use the 2-links trick from kpse when exploring trees? Check how it works on
windows.


Using the catalogue
-------------------

Obsolescence information could be useful (Phil's suggestion), but may be hard to
obtain (not in the tlpdb)... Well, if it's in the catalogue, I can ship a
Data.obsolete.lua file with the information...

Do something with the description from the catalogue?

Help maintainers standardise comments in order to allow for more accurate
scoring/classification?

--apropos using Jim's keywords and categorization, see Karl's mail:
http://tug.org/pipermail/texdoc/2010q3/000213.html


Auto-generation of doc files ???
--------------------------------

To allow installing TL without the doc trees (cuts off the size by 2).
Suggested by Will.


Port on MikTeX ???
------------------

Lots of TeX-live specific stuff (implicitly) embedded in various places...

Add a function in texlua's kpse library returning all files for which a certain
Lua function (given as argument) returns true. Use only it.

What to do with all the functions using tlpdb? Is it possible to use an
equivalent on MikTeX?

Adapt to the different tree layout in MikTeX (TEXMFHOME etc don't exist).

How to detect the distro? What to do with aliases?


Notes and references
--------------------

Texdoc GUI project going on since early May 2010, see messages from Enrico
Gregorio in my (mpg) inbox.

Used by vim script #2945 (AutomaticTexPlugin) as F1 and :TexDoc.
Clone this wiki locally