====== Text File Sections ======

A //Text File Section// is a sysop-curated collection of text files made available to users for reading. Common uses are bulletins, ANSI art galleries, BBS information, news archives, and similar non-credit-bearing reading material. Text File Sections are distinct from the [[config:file_areas|file transfer section]] — files in a text section are read in-line through the BBS terminal interface, not downloaded, and are not subject to credit/transfer access controls.

Text File Sections are configured in [[util:scfg|SCFG]] → //Text File Sections//.

===== Section List =====

  ╔═══════════════════════════════════════════╗
  ║             Text File Sections            ║
  ╠═══════════════════════════════════════════╣
  ║ │Information                              ║
  ║ │ANSI Artwork                             ║
  ║ │ANSI Music Files                         ║
  ║ │PETSCII Artwork                          ║
  ║ │RIP Art                                  ║
  ║ │UTF-8 Tests                              ║
  ║ │Operator                                 ║
  ║ │PCBoard Display Files                    ║
  ║ │Wildcat! Display Files                   ║
  ║ │VT100 art                                ║
  ╚═══════════════════════════════════════════╝

  * ''Ins'' or ''+'' — add a new section
  * ''Del'' or ''-'' — delete a section
  * ''F5'' / ''Ctrl-C'', ''F6'' / ''Ctrl-V'' — copy / paste a section
  * Press ''Enter'' on a section to edit it.

When adding a section, SCFG prompts for a //Name// and an //Internal Code//. The internal code becomes the on-disk identifier for the section (and the name of the data subdirectory).

===== Per-Section Options =====

  ╔══════════════════════════════════════════════════════════╗
  ║                        Information                       ║
  ╠══════════════════════════════════════════════════════════╣
  ║ │Name                       Information                  ║
  ║ │Internal Code              INFO                         ║
  ║ │Access Requirements                                     ║
  ╚══════════════════════════════════════════════════════════╝

^ Option Name         ^ Description ^
| Name                | Display name shown to users in the section list. |
| Internal Code       | Up to 8 valid filename characters; uniquely identifies this section in storage. The lowercased code is also used as the on-disk subdirectory name. |
| Access Requirements | An [[access:requirements|ARS]] expression — users not matching the requirements cannot see or access the section. Blank = open to all. |

===== File Storage =====

Each section's text files live in:

  * ''[[dir:data]]/text/<code>/'' — text files for the section (any text format: ASCII, ANSI, UTF-8, etc.). Created automatically by SCFG when the section is saved.
  * ''[[dir:data]]/text/<code>.ini'' — //optional// per-section metadata file (see [[#section_ini_file|below]]).

The configuration of the sections themselves (the ''[text:CODE]'' blocks) is persisted to ''[[dir:ctrl]]/[[config:file.ini]]''.

==== Section .ini File ====

If present at ''[[dir:data]]/text/<code>.ini'', this file is read by the default renderer ([[:dir:exec]]/text_sec.js) and gives the sysop control over presentation defaults and per-file overrides.

=== Root section keys ===

Keys placed before any ''[<filename>]'' section header apply to the entire text section as defaults:

^ Key    ^ Default      ^ Description ^
| ''mode'' | ''P_CPM_EOF'' | Default //pmode// flags passed to ''console.printfile()'' for files in this section. Value is a JavaScript expression of one or more ''P_*'' constants combined with ''%%|%%''. See the [[#pmode_flag_reference|pmode flag reference]] below. |
| ''cols'' | //undefined// (use terminal width) | Column count to format file output to. Files are wrapped or truncated to this width depending on the ''mode'' flags. |

Example minimal section .ini:
<code ini>
mode=P_CPM_EOF | P_NOATCODES
cols=80
</code>

=== Per-file sections ===

Each ''[<key>]'' header in the .ini file describes one displayable file in the section. The ''<key>'' is a sysop-chosen short identifier the user types to view the file.

^ Field    ^ Description ^
| ''name'' | The actual filename in ''[[dir:data]]/text/<code>/''. |
| ''desc'' | Descriptive title shown in the file list. |
| ''ars''  | Optional [[access:requirements|ARS]] for this individual file. |
| ''mode'' | Optional override of the [[#root_section_keys|section default ''mode'']] for this file. |
| ''cols'' | Optional override of the section default ''cols'' for this file. |
| ''petscii_graphics'' | If set, the file is treated as native PETSCII graphics. |
| ''tail'' | If set to a positive integer N, only the last N lines of the file are displayed (uses ''console.printtail''). |

Example:
<code ini>
mode=P_CPM_EOF
cols=80

[news]
name=news.asc
desc=Latest BBS news
mode=P_CPM_EOF | P_AUTO_UTF8

[c64]
name=welcome.pet
desc=Welcome (PETSCII)
petscii_graphics=true

[changelog]
name=CHANGELOG
desc=Recent changes (last 50 lines)
tail=50
</code>

=== pmode flag reference ===

The ''mode'' value is a JavaScript expression of pmode constants (defined in ''sbbsdefs.js'' / ''sbbsdefs.h''), bitwise-OR'd with ''%%|%%''. Most commonly used:

^ Constant      ^ Meaning ^
| ''P_NONE''    | No flags. |
| ''P_NOABORT'' | User cannot abort the display with ''Ctrl-C''. |
| ''P_SAVEATR'' | Save current text attributes after display. |
| ''P_NOATCODES'' | Don't process [[custom:atcodes|@-codes]] in the file. |
| ''P_NOPAUSE'' | Disable the //hit a key// pause prompt at end-of-screen. |
| ''P_SEEK''    | Allow keyboard navigation (Home/End/PgUp/PgDn) within the file. |
| ''P_NOCRLF''  | Don't emit a CRLF before the file content. |
| ''P_WORDWRAP'' | Word-wrap long lines for the user's terminal. |
| ''P_CPM_EOF'' | Stop parsing/displaying at ''Ctrl-Z'' (CP/M end-of-file convention). The default. |
| ''P_TRUNCATE'' | Truncate (rather than wrap) lines longer than ''cols''. |
| ''P_PETSCII''  | File is native PETSCII. |
| ''P_UTF8''     | File is UTF-8 encoded. |
| ''P_AUTO_UTF8'' | Auto-detect UTF-8 content. |
| ''P_MARKUP''   | Process StyleCodes / Rich / StructuredText markup. |
| ''P_HIDEMARKS'' | Hide markup source characters from the rendered output. |
| ''P_NOXATTRS'' | Disable "Extra Attribute Codes" processing. |

The full set is defined in ''src/sbbs3/sbbsdefs.h''.

===== Adding Files to a Section =====

There are two ways to populate a Text File Section:

==== Via the BBS (sysop) ====
Log into the BBS, enter the //Text// option of the main menu, choose the section, and use the //Add// command. The sysop is prompted for the title and the path/filename. If no path is given, the file is read from the section's data directory.

==== Directly on the filesystem ====
Drop files into ''[[dir:data]]/text/<code>/''. Optionally edit ''[[dir:data]]/text/<code>.ini'' to set display order and friendly titles.

===== Renderer (Loadable Module) =====

The module that presents Text File Sections to users is configured in [[util:scfg|SCFG]] → //System// → //Loadable Modules// → //Text Section//. The default is ''text_sec'' (i.e. ''[[:dir:exec]]/text_sec.js''). Sysops wanting a custom navigation experience can replace this with their own JavaScript module.

===== Recommended Sections =====

A reasonable baseline:

  * **Information** (''INFO'') — general BBS info; consider including ''[[:dir:text]]/sbbs.msg''
  * **Operator** (''OPERATOR'', ''ars=SYSOP'') — sysop-only system notes / change logs
  * **ANSI Artwork** (''ANSI'') — and sibling sections (''PETSCII'', ''RIP'', ''VT100ART'', ''UTF8'') for systems catering to retro terminals

It is requested that sysops make at least the ''[[:dir:text]]/sbbs.msg'' file available somewhere reachable for users.

===== See Also =====
  * [[:config:|Configuration index]]
  * [[:util:scfg|SCFG]]
  * [[:config:file.ini|file.ini]]
  * [[:config:text_files|Text Files]] (system display files, distinct topic)
  * [[:config:file_areas|File Areas]] (transfer / download section)
  * [[:dir:data]]

{{tag>configuration text_files scfg}}
