[BACK]Return to mandoc.db.5 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.db.5 between version 1.4 and 1.5

version 1.4, 2016/07/07 14:35:48 version 1.5, 2016/08/01 12:27:15
Line 1 
Line 1 
 .\"     $Id$  .\"     $Id$
 .\"  .\"
 .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>  .\" Copyright (c) 2014, 2016 Ingo Schwarze <schwarze@openbsd.org>
 .\"  .\"
 .\" Permission to use, copy, modify, and distribute this software for any  .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above  .\" purpose with or without fee is hereby granted, provided that the above
Line 23 
Line 23 
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm  .Nm
 SQLite3 file format is used to store information about installed manual  file format is used to store information about installed manual
 pages to facilitate semantic searching for manuals.  pages to facilitate semantic searching for manuals.
 Each manual page tree contains its own  Each manual page tree contains its own
 .Nm  .Nm
Line 34  for examples.
Line 34  for examples.
 Such database files are generated by  Such database files are generated by
 .Xr makewhatis 8  .Xr makewhatis 8
 and used by  and used by
   .Xr man 1 ,
 .Xr apropos 1  .Xr apropos 1
 and  and
 .Xr whatis 1 .  .Xr whatis 1 .
 .Pp  .Pp
 One line in the following tables describes:  The file format uses three datatypes:
 .Bl -tag -width Ds  .Pp
 .It Sy mpages  .Bl -dash -compact -offset 2n -width 1n
 One physical manual page file, no matter how many times and under which  .It
 names it may appear in the file system.  32-bit signed integer numbers in big endian (network) byte ordering
 .It Sy mlinks  .It
 One entry in the file system, no matter which content it points to.  NUL-terminated strings
 .It Sy names  .It
 One manual page name, no matter whether it appears in a page header,  lists of NUL-terminated strings, terminated by a second NUL character
 in a NAME or SYNOPSIS section, or as a file name.  
 .It Sy keys  
 One chunk of text from some macro invocation.  
 .El  .El
 .Pp  .Pp
 Each record in the latter three tables uses its  Numbers are aligned to four-byte boundaries; where they follow
 .Va pageid  strings or lists of strings, padding with additional NUL characters
 column to point to a record in the  occurs.
 .Sy mpages  Some, but not all, numbers point to positions in the file.
 table.  These pointers are measured in bytes, and the first byte of the
   file is considered to be byte 0.
 .Pp  .Pp
 The other columns are as follows; unless stated otherwise, they are  Each file consists of:
 of type  .Pp
 .Vt TEXT .  .Bl -dash -compact -offset 2n -width 1n
 .Bl -tag -width mpages.desc  .It
 .It Sy mpages.desc  One magic number, 0x3a7d0cdb.
 The description line  .It
 .Pq Sq \&Nd  One version number, currently 1.
 of the page.  .It
 .It Sy mpages.form  One pointer to the macros table.
 An  .It
 .Vt INTEGER  One pointer to the final magic number.
 bit field.  .It
 If bit  The pages table (variable length).
 .Dv FORM_GZ  .It
 is set, the page is compressed and requires  The macros table (variable length).
 .Xr gunzip 1  .It
 for display.  The magic number once again, 0x3a7d0cdb.
 If bit  .El
 .Dv FORM_SRC  .Pp
 is set, the page is unformatted, that is in  The pages table contains one entry for each physical manual page
   file, no matter how many hard and soft links it may have in the
   file system.
   The pages table consists of:
   .Pp
   .Bl -dash -compact -offset 2n -width 1n
   .It
   The number of pages in the database.
   .It
   For each page:
   .Bl -dash -compact -offset 2n -width 1n
   .It
   One pointer to the list of names.
   .It
   One pointer to the list of sections.
   .It
   One pointer to the list of architectures
   or 0 if the page is machine-independent.
   .It
   One pointer to the one-line description string.
   .It
   One pointer to the list of filenames.
   .El
   .It
   For each page, the list of names.
   Each name is preceded by a single byte indicating the sources of the name.
   The meaning of the bits is:
   .Bl -dash -compact -offset 2n -width 1n
   .It
   0x10: The name appears in a filename.
   .It
   0x08: The name appears in a header line, i.e. in a .Dt or .TH macro.
   .It
   0x04: The name is the first one in the title line, i.e. it appears
   in the first .Nm macro in the NAME section.
   .It
   0x02: The name appears in any .Nm macro in the NAME section.
   .It
   0x01: The name appears in an .Nm block in the SYNOPSIS section.
   .El
   .It
   For each page, the list of sections.
   Each section is given as a string, not as a number.
   .It
   For each architecture-dependent page, the list of architectures.
   .It
   For each page, the one-line description string taken from the .Nd macro.
   .It
   For each page, the list of filenames relative to the root of the
   respective manpath.
   This list includes hard links, soft links, and links simulated
   with .so
   .Xr roff 7
   requests.
   The first filename is preceded by a single byte
   having the following significance:
   .Bl -dash -compact -offset 2n -width 1n
   .It
   .Dv FORM_SRC No = 0x01 :
   The file format is
 .Xr mdoc 7  .Xr mdoc 7
 or  or
 .Xr man 7  .Xr man 7 .
 format, and requires  .It
 .Xr mandoc 1  .Dv FORM_CAT No = 0x02 :
 for display.  The manual page is preformatted.
 If bit  .El
 .Dv FORM_SRC  .It
 is not set, the page is formatted, i.e. a  Zero to three NUL bytes for padding.
 .Sq cat  .El
 page.  .Pp
 .It Sy mlinks.sec  The macros table consists of:
 The manual section as found in the subdirectory name.  .Pp
 .It Sy mlinks.arch  .Bl -dash -compact -offset 2n -width 1n
 The manual architecture as found in the subdirectory name, or  .It
 .Qq any .  The number of different macro keys, currently 36.
 .It Sy mlinks.name  The ordering of macros is defined in
 The manual name as found in the file name.  .In mansearch.h
 .It Sy names.bits  and the significance of the macro keys is documented in
 An  
 .Vt INTEGER  
 bit mask telling whether the name came from a header line, from the  
 NAME or SYNOPSIS section, or from a file name.  
 Bits are defined in  
 .In mansearch.h .  
 .It Sy names.name  
 The name itself.  
 .It Sy keys.bits  
 An  
 .Vt INTEGER  
 bit mask telling which semantic contexts the key was found in;  
 defined in  
 .In mansearch.h ,  
 documented in  
 .Xr apropos 1 .  .Xr apropos 1 .
 .It Sy keys.key  .It
 The string found in those contexts.  For each macro key, one pointer to the respective macro table.
   .It
   For each macro key, the macro table (variable length).
 .El  .El
   .Pp
   Each macro table consists of:
   .Pp
   .Bl -dash -compact -offset 2n -width 1n
   .It
   The number of entries in the table.
   .It
   For each entry:
   .Bl -dash -compact -offset 2n -width 1n
   .It
   One pointer to the value of the macro key.
   Each value is a string of text taken from some macro invocation.
   .It
   One pointer to the list of pages.
   .El
   .It
   For each entry, the value of the macro key.
   .It
   Zero to three NUL bytes for padding.
   .It
   For each entry, one or more pointers to pages in the pages table,
   pointing to the pointer to the list of names,
   followed by the number 0.
   .El
 .Sh FILES  .Sh FILES
 .Bl -tag -width /usr/share/man/mandoc.db -compact  .Bl -tag -width /usr/share/man/mandoc.db -compact
 .It Pa /usr/share/man/mandoc.db  .It Pa /usr/share/man/mandoc.db
Line 128  Window System.
Line 197  Window System.
 The same for  The same for
 .Xr packages 7 .  .Xr packages 7 .
 .El  .El
   .Pp
   A program to dump
   .Nm
   files in a human-readable format suitable for
   .Xr diff 1
   is provided in the directory
   .Pa /usr/src/regress/usr.bin/mandoc/db/dbm_dump/ .
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr apropos 1 ,  .Xr apropos 1 ,
 .Xr man 1 ,  .Xr man 1 ,
 .Xr sqlite3 1 ,  
 .Xr whatis 1 ,  .Xr whatis 1 ,
 .Xr makewhatis 8  .Xr makewhatis 8
 .Sh HISTORY  .Sh HISTORY
Line 140  A manual page database
Line 215  A manual page database
 first appeared in  first appeared in
 .Bx 2 .  .Bx 2 .
 The present format first appeared in  The present format first appeared in
 .Ox 5.6 .  .Ox 6.1 .
 .Sh AUTHORS  .Sh AUTHORS
 .An -nosplit  .An -nosplit
 The original version of  The original version of
Line 148  The original version of
Line 223  The original version of
 was written by  was written by
 .An Bill Joy  .An Bill Joy
 in 1979.  in 1979.
 An SQLite3 version was first implemented by  
 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv  
 in 2012.  
 The present database format was designed by  The present database format was designed by
 .An Ingo Schwarze Aq Mt schwarze@openbsd.org  .An Ingo Schwarze Aq Mt schwarze@openbsd.org
 in 2014.  in 2016.

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5

CVSweb