Re: [sqlite] Documentation improvement request

[Warren Young]

On Feb 8, 2020, at 11:56 AM, Simon Slavin  wrote:
> 
> ?  I don't know whether this can be done automatically.  Possibly for any 
> page which has section headers.

Yes, it can be done, and I’ve lined out several options for doing so here:

https://www.fossil-scm.org/forum/forumpost/a5e1391eb3

Someone now needs to decide this is their itch and teach Fossil how to do one 
of these things.

___
sqlite-users mailing list
sqlite-users@mailinglists.sqlite.org
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users

[sqlite] Documentation improvement request

[Simon Slavin]

Some pages in the documentation started small but had stuff gradually added to 
them over the years.  For the pages




can a "Table Of Contents" be added at the top, like the one on



?  I don't know whether this can be done automatically.  Possibly for any page 
which has section headers.
___
sqlite-users mailing list
sqlite-users@mailinglists.sqlite.org
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users

[sqlite] Documentation improvement request: PRAGMAs

[Simon Slavin]

If I got this right, there are five types of PRAGMA:

A) some return information without making changes
B) some affect the loaded SQLite library: all connections and future 
connections until the library is unloaded
C) some change the behaviour of one connection without changing anything in the 
database, but reopening the database file won't know they've happened
D) some change something saved in the database file, and reopening the database 
file will see the change
E) some do something to the open database, but don't change a queriable setting

Examples:

A) PRAGMA database_list 
B) PRAGMA default_cache_size = Number-of-pages
C) PRAGMA locking_mode
D) PRAGMA application_id = integer
E) PRAGMA incremental_vacuum(N)

The PRAGMA documentation page is often clear on which PRAGMA is in which 
category, but sometimes not.  For instance, the description for

PRAGMA auto_vacuum

says

"Query or set the auto-vacuum status in the database.
[...]
The database connection can be changed between full and incremental autovacuum 
mode at any time."

which suggests first (D) then (C).  My guess is that it's actually (D) and that 
the wording in the second part should be changed.  But I might be wrong.

The descriptions of some PRAGMAs -- for example PRAGMA cache_spill -- are 
unclear.  You have to have some appreciation of how SQLite works to understand 
which category the PRAGMA is in.  I ask that someone familiar with how SQLite 
works internally go through the PRAGMA page and check to see the descriptions 
are clear.

As part of that, or as a separate exercise, or perhaps just for SQLite4, it 
might be nice to devise a category system (you can probably improve on my (A) 
to (E) one) and state explicitly which category each PRAGMA is in on the page.  
Or perhaps split the PRAGMA documentation page into five (or however many it 
is) sections or separate pages.  I learned a useful thing about SQLite by just 
trying to categorise each PRAGMA using my own categories.

Simon.
___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users

[sqlite] Documentation improvement request

[Simon Slavin]

I think it would be useful if



mentioned that there was a PRAGMA that did the same thing:



This would help people who aren't calling the SQLite API directly but are 
working with a more restrictive shim API.

The reverse reference for this function is already present.  However, it might 
be worth going through all the PRAGMAs which duplicate API calls and mentioning 
them in the documentation for those calls.

Simon.
___
sqlite-users mailing list
sqlite-users@sqlite.org
http://sqlite.org:8080/cgi-bin/mailman/listinfo/sqlite-users