Skip to content

TODO

Jump to bottom
Takuto ASAKURA edited this page Aug 28, 2022 · 8 revisions

Finding documents outside TeX Live

Currently, Texdoc has only limited features 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 ideas or suggestions, please leave comments there.

Possible solution: alias variant (alias*)

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

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

This feature will allow users to access documents that they want to open via Texdoc, but cannot find the right position for it in a TEXMF tree.

Query substitution

The alias function is to register "a query to a document" pointers and not provide "a query to another query" substitution. Therefore, it is naturally weak against changes in the doc trees. I also sometimes want to have the latter function. And this might better be implemented as a different function from the alias function.

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 is 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 the Texdoc function (i.e., searching, scoring, and determining which documents to show) and it is not worth spending time and calculation 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 an ordered data structure for storing document lists (again, it doesn't have to be in lexicographical order. All we need is an order-stable data structure). This solution is ideal because it will not add unnecessary calculation processes.

cf. issue #24

Scoring overhaul

A 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 designed by the former maintainer (mpg). Respecting that fact, we keep the design for now, but some people might think it is not so readable (e.g., is it suitable to use a sans-serif font for the text?).

We know that it is extremely difficult to make a design that is agreed upon 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 design of the document, but still, we should try to make the document more readable for many people.

Misc

  • Add comprehensive test scripts
  • Make the list of good and/or bad comments from the catalog 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 documents by the 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