ARCHIVE: Reorganization: docs.perl6.org

Problems with the current setup:

• fragile
• tight coupling between presentation rendering and source data
• no live test for checking major changes

Reorganization proposal [WIP]:

1. Do not change hidden directories.

2. Move non-English READMEs to the resources/ directory and link to them from the English README at the top level. [DONE]

3. Directories to be removed or moved:

    bin/             # remove
        p6doc        # move to another repo
    assets/          # move to resources/
    highlghts/       # move to resources/
    template/        # move to resources/
   

4. Directories remaining:

    doc/             # all source pod6 documents for publication
    resources/       # all source docs needed by the build tools
    util/            # all build tools (add suffix to indicate type: shell, Perl 6, etc.)
    build/           # non-versioned,transient directory of build products
    html/            # non-versioned, transient directory of html products for publishing
    writing-docs/    # information for contributors
    lib/
    xt/
    t/
   

Robustness proposal [WIP]:

1. add comments to htmlify.p6 and other documents to explain the doc build process

2. make build subs more generic, less coupled to specific directories

3. consider forking pod2onepage to the doc repo

4. expand on ease of maintenance via a control file for a major pod6 source directory such as Language

The control file [WIP]

The control file is located in the appropriate pod 6 source directory and is used as an easy-to-see source for the order and sectioning of a set of files. In the current reorganization effort it is located as shown:

doc/
    Language/
        00-POD6-CONTROL
        ...pod 6 source files...

The format of the control file can be seen in the current control file in the doc subdirectory of the perl6/doc repository.