diff --git a/l3build-manifest-setup.lua b/l3build-manifest-setup.lua new file mode 100644 index 00000000..9aa30482 --- /dev/null +++ b/l3build-manifest-setup.lua @@ -0,0 +1,247 @@ +--[[ + +File l3build.lua Copyright (C) 2014-2017 The LaTeX3 Project + +It may be distributed and/or modified under the conditions of the +LaTeX Project Public License (LPPL), either version 1.3c of this +license or (at your option) any later version. The latest version +of this license is in the file + + http://www.latex-project.org/lppl.txt + +This file is part of the "l3build bundle" (The Work in LPPL) +and all files in that bundle must be distributed together. + +----------------------------------------------------------------------- + +The development version of the bundle can be found at + + https://github.com/latex3/l3build + +for those people who are interested. + +--]] + + +--[[ + L3BUILD MANIFEST SETUP + ====================== + This file contains all of the code that is easily replaceable by the user. + Either create a copy of this file, rename, and include alongside your `build.lua` + script and load it with `dofile()`, or simply copy/paste the definitions below + into your `build.lua` script directly. +--]] + + +--[[ + Setup of manifest "groups" + -------------------------- +--]] + +manifest_setup = manifest_setup or function() + local groups = { + { + name = "Source files", + description = [[ +These are source files for a number of purposes, including the `unpack` +process which generates the installation files of the package. Additional +files included here will also be installed for processing such as testing. + ]], + files = {sourcefiles}, + }, + { + name = "Typeset documentation source files", + description = [[ +These files are typeset using LaTeX to produce the PDF documentation for the package. + ]], + files = {typesetfiles,typesetsourcefiles,typesetdemofiles}, + }, + { + name = "Documentation files", + description = [[ +These files form part of the documentation but are not typeset. +Generally they will be additional input files for the typeset +documentation files listed above. + ]], + files = {docfiles}, + }, + { + name = "Text files", + files = {textfiles}, + extractfiledesc = false, + }, + { + name = "Demo files", + files = {demofiles}, + }, + { + name = "Bibliography and index files", + files = {bibfiles,bstfiles,makeindexfiles}, + }, + { + name = "Derived files", + files = {installfiles}, + exclude = {excludefiles,sourcefiles}, + dir = unpackdir, + extractfiledesc = false, + }, + { + name = "Typeset documents", + files = {typesetfiles,typesetsourcefiles,typesetdemofiles}, + rename = {"%.%w+$", ".pdf"}, + }, + { + name = "Support files needed for unpacking, typesetting, or checking", + files = {unpacksuppfiles,typesetsuppfiles,checksuppfiles}, + dir = supportdir, + }, + { + name = "Checking-specific support files", + files = {"*.*"}, + exclude = {{".",".."},excludefiles}, + dir = testsuppdir, + }, + { + name = "Test files", + description = [[ +These files form the test suite for the package. +`.lvt` or `.lte` files are the individual unit tests, +and `.tlg` are the stored output for ensuring changes +to the package produce the same output. These output +files are sometimes shared and sometime specific for +different engines (pdfTeX, XeTeX, LuaTeX, etc.). + ]], + files = {"*"..lvtext,"*"..lveext,"*"..tlgext}, + dir = testfiledir, + extractfiledesc = false, + }, + } + return groups +end + +--[[ + Sorting within groups + --------------------- +--]] + +manifest_sort_within_glob = manifest_sort_within_glob or function(files) + table.sort(files) + return files +end + +manifest_sort_within_group = manifest_sort_within_group or function(files) + --[[ + -- no-op by default; make your own definition to customise. E.g.: + table.sort(files) + --]] + return files +end + +--[[ + Writing to file + --------------- +--]] + +manifest_write_opening = manifest_write_opening or function(filehandle) + + filehandle:write("# Manifest for " .. module .. "\n\n") + filehandle:write("This file is automatically generated with `texlua build.lua manifest`.\n") + +end + +manifest_write_group_heading = manifest_write_group_heading or function (filehandle,heading) + + filehandle:write("\n## " .. heading .. "\n\n") + +end + +manifest_write_group_description = manifest_write_group_description or function(filehandle,description) +-- Redefine as a no-op if you don't like each group to have a written description. + + filehandle:write(description .. "\n") + +end + +manifest_write_group_file = manifest_write_group_file or function(filehandle,count,filename,Nchar) + --[[ + filehandle : write file object + count : the count of the filename to be written + filename : the name of the file to write + Nchar : the maximum number of chars of all filenames in this group + --]] + + -- no file description: plain bullet list item: + filehandle:write("* " .. filename .. "\n") + + --[[ + -- or if you prefer an enumerated list: + filehandle:write(count..". " .. filename .. "\n") + --]] + + +end + +manifest_write_group_file_descr = manifest_write_group_file_descr or function(filehandle,count,filename,Nchar,descr,NcharD) + --[[ + filehandle : write file object + count : the count of the filename to be written + filename : the name of the file to write + Nchar : the maximum number of chars of all filenames in this group + descr : description of the file to write + NcharD : the maximum number of chars of all descriptions in this group + --]] + + -- filename+description: Github-flavoured Markdown table + + if count==1 then + -- header of table + manifest_write_group_file_descr(filehandle,-1,"File",Nchar,"Description",NcharD) + manifest_write_group_file_descr(filehandle,-1,"---", Nchar,"---", NcharD) + end + + filehandle:write(string.format( + " | %-"..Nchar .."s | %-"..NcharD.."s |\n", + filename,descr)) + +end + +--[[ + Extracting ‘descriptions’ from source files + ------------------------------------------- +--]] + +manifest_extract_filedesc = manifest_extract_filedesc or function(filehandle) +-- no-op by default; two examples below +end + +--[[ + +-- From the first match of a pattern in a file: +manifest_extract_filedesc = function(filehandle) + + local read_string = "*all" + local matchstr = "\\section{(.-)}" + + all_file = filehandle:read(read_string) + + return string.match(all_file,matchstr) + +end + +-- From the match of the 2nd line (say) of a file: +manifest_extract_filedesc = function(filehandle) + + local end_read_loop = 2 + local read_string = "*line" + local matchstr = "%%%S%s+(.*)" + local this_line = "" + + for ii = 1, end_read_loop do + this_line = filehandle:read(read_string) + end + + return string.match(this_line,matchstr) + +end + +]]-- diff --git a/l3build-manifest.lua b/l3build-manifest.lua index 8205c9fe..5a542410 100644 --- a/l3build-manifest.lua +++ b/l3build-manifest.lua @@ -23,6 +23,16 @@ for those people who are interested. --]] +--[[ + L3BUILD MANIFEST + ================ + If desired this entire function can be replaced; if not, it uses a number of + auxiliary functions which are included in this file. + + Additional setup can be performed by replacing the functions lists in the file + `l3build-manifest-setup.lua`. +--]] + manifest = manifest or function() manifest_lists = manifest_setup() @@ -33,96 +43,17 @@ manifest = manifest or function() manifest_write(manifest_lists) -end - - + printline = "Manifest written to " .. manifestfile + print((printline:gsub(".","*"))) print(printline) print((printline:gsub(".","*"))) -manifest_setup = manifest_setup or function() --- this needs to be an array of tables, not a table of tables, to ensure ordering. - local groups = { - { - name = "Source files", - description = [[ -These are source files for a number of purposes, including the `unpack` -process which generates the installation files of the package. Additional -files included here will also be installed for processing such as testing. - ]], - files = {sourcefiles}, - }, - { - name = "Typeset documentation source files", - description = [[ -These files are typeset using LaTeX to produce the PDF documentation for the package. - ]], - files = {typesetfiles,typesetsourcefiles,typesetdemofiles}, - }, - { - name = "Documentation files", - description = [[ -These files form part of the documentation but are not typeset. -Generally they will be additional input files for the typeset -documentation files listed above. - ]], - files = {docfiles}, - }, - { - name = "Text files", - files = {textfiles}, - extractfiledesc = false, - }, - { - name = "Demo files", - files = {demofiles}, - }, - { - name = "Bibliography and index files", - files = {bibfiles,bstfiles,makeindexfiles}, - }, - { - name = "Derived files", - files = {installfiles}, - exclude = {excludefiles,sourcefiles}, - dir = unpackdir, - extractfiledesc = false, - }, - { - name = "Typeset documents", - files = {typesetfiles,typesetsourcefiles,typesetdemofiles}, - rename = {"%.%w+$", ".pdf"}, - }, - { - name = "Support files needed for unpacking, typesetting, or checking", - files = {unpacksuppfiles,typesetsuppfiles,checksuppfiles}, - dir = supportdir, - }, - { - name = "Checking-specific support files", - files = {"*.*"}, - exclude = {{".",".."},excludefiles}, - dir = testsuppdir, - }, - { - name = "Test files", - description = [[ -These files form the test suite for the package. -`.lvt` or `.lte` files are the individual unit tests, -and `.tlg` are the stored output for ensuring changes -to the package produce the same output. These output -files are sometimes shared and sometime specific for -different engines (pdfTeX, XeTeX, LuaTeX, etc.). - ]], - files = {"*"..lvtext,"*"..lveext,"*"..tlgext}, - dir = testfiledir, - extractfiledesc = false, - }, - } - return groups end +--[[ + Internal Manifest functions: build_list + --------------------------------------- +--]] - - -manifest_build_list = manifest_build_list or function(manifest_list) +manifest_build_list = function(manifest_list) manifest_list = manifest_build_init(manifest_list) @@ -193,9 +124,10 @@ manifest_build_list = manifest_build_list or function(manifest_list) end -manifest_build_init = manifest_build_init or function(manifest_list) --- currently these aren't customisable; I guess they could/should be? +manifest_build_init = function(manifest_list) + + -- currently these aren't customisable; I guess they could/should be? local manifest_group_defaults = { extractfiledesc = true , rename = false , @@ -237,8 +169,12 @@ manifest_build_init = manifest_build_init or function(manifest_list) end +--[[ + Internal Manifest functions: write + ---------------------------------- +--]] -manifest_write = manifest_write or function(manifest_lists) +manifest_write = function(manifest_lists) local f = assert(io.open(manifestfile, "w")) manifest_write_opening(f) @@ -251,15 +187,10 @@ manifest_write = manifest_write or function(manifest_lists) f:close() - printline = "Manifest written to " .. manifestfile - print((printline:gsub(".","*"))) - print(printline) - print((printline:gsub(".","*"))) - end -manifest_write_group = manifest_write_group or function(f,manifest_list) +manifest_write_group = function(f,manifest_list) manifest_write_group_heading(f,manifest_list.name) @@ -288,115 +219,3 @@ manifest_write_group = manifest_write_group or function(f,manifest_list) end - -manifest_write_opening = manifest_write_opening or function(filehandle) - - filehandle:write("# Manifest for " .. module .. "\n\n") - filehandle:write("This file is automatically generated with `texlua build.lua manifest`.\n") - -end - -manifest_write_group_heading = manifest_write_group_heading or function (filehandle,heading) - - filehandle:write("\n## " .. heading .. "\n\n") - -end - -manifest_write_group_description = manifest_write_group_description or function(filehandle,description) --- Redefine as a no-op if you don't like each group to have a written description. - - filehandle:write(description .. "\n") - -end - -manifest_write_group_file = manifest_write_group_file or function(filehandle,count,filename,Nchar) - --[[ - filehandle : write file object - count : the count of the filename to be written - filename : the name of the file to write - Nchar : the maximum number of chars of all filenames in this group - --]] - - -- no file description: plain bullet list item: - filehandle:write("* " .. filename .. "\n") - - --[[ - -- or if you prefer an enumerated list: - filehandle:write(count..". " .. filename .. "\n") - --]] - - -end - -manifest_write_group_file_descr = manifest_write_group_file_descr or function(filehandle,count,filename,Nchar,descr,NcharD) - --[[ - filehandle : write file object - count : the count of the filename to be written - filename : the name of the file to write - Nchar : the maximum number of chars of all filenames in this group - descr : description of the file to write - NcharD : the maximum number of chars of all descriptions in this group - --]] - - -- filename+description: Github-flavoured Markdown table - - if count==1 then - -- header of table - manifest_write_group_file_descr(filehandle,-1,"File",Nchar,"Description",NcharD) - manifest_write_group_file_descr(filehandle,-1,"---", Nchar,"---", NcharD) - end - - filehandle:write(string.format( - " | %-"..Nchar .."s | %-"..NcharD.."s |\n", - filename,descr)) - -end - -manifest_sort_within_glob = manifest_sort_within_glob or function(files) - table.sort(files) - return files -end - -manifest_sort_within_group = manifest_sort_within_group or function(files) - --[[ - -- no-op by default; make your own definition to customise. E.g.: - table.sort(files) - --]] - return files -end - -manifest_extract_filedesc = manifest_extract_filedesc or function(filehandle) --- no-op by default; two examples below -end - ---[[ - --- From the first match of a pattern in a file: -manifest_extract_filedesc = function(filehandle) - - local read_string = "*all" - local matchstr = "\\section{(.-)}" - - all_file = filehandle:read(read_string) - - return string.match(all_file,matchstr) - -end - --- From the match of the 2nd line (say) of a file: -manifest_extract_filedesc = function(filehandle) - - local end_read_loop = 2 - local read_string = "*line" - local matchstr = "%%%S%s+(.*)" - local this_line = "" - - for ii = 1, end_read_loop do - this_line = filehandle:read(read_string) - end - - return string.match(this_line,matchstr) - -end - -]]-- diff --git a/l3build.lua b/l3build.lua index 01e6bd0e..34843ff7 100644 --- a/l3build.lua +++ b/l3build.lua @@ -2362,6 +2362,7 @@ end kpse.set_program_name("kpsewhich") build_kpse_path = dirname(kpse.lookup("l3build.lua")) require( kpse.lookup("l3build-manifest.lua", { path = build_kpse_path } ) ) +require( kpse.lookup("l3build-manifest-setup.lua", { path = build_kpse_path } ) ) function version()