Merge pull request #19 from revdavethompson/0.3.4-README

0.3.4 readme

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.3.3] - 2023-5-17
+
+### Added
+
+* New README.md for create-bookpub-project package
+    * Copied over the console help message
+    * Copied over the output when a new project is generated.
+
+### Changed
+
+* Updated README.md
+    * Now reflects new installation procedure with `npx create-bookpub-project
+    * Cleaned up some content so it is clearer and in some cases correct. ;-)
+
 ## [0.3.1] - 2023-5-16
 
 ### Added

README.md

@@ -55,31 +55,39 @@ BookPub manages a manuscript-to-market toolchain, allowing publishing firms, aut
 
       `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash`
 
-### Installing **BookPub**
+* [PrinceXML](https://princexml.com) - You will need to install PrinceXML to build PDFs
 
-  * From the command line:
+  We've chosen the PrinceXML library because it is the best available for converting HTML/CSS/Javascript to Print-Ready PDFs. (At some point we may add other options.)
 
-    `npm install -g bookpub`
+  * [Installation and Setup Instructions Here](https://www.princexml.com/doc/installing/)
 
-    It is important to use the `-g` (global) flag when installing BookPub. This will install BookPub system-wide. BookPub is a (CLI) "command-line interface", so you will need to be able to execute `bookpub` from anywhere on your command-line (terminal).
+### Creating a New **BookPub** Project
 
-### Install PrinceXML (to build PDFs)
+  * From the command line, type:
 
-  * [Installation and Setup Instructions Here](https://www.princexml.com/doc/installing/)
+    `npx create-bookpub-project`
 
-## Usage
+    <small>*If this is your first time, please select (y) when prompted.*</small>
+
+    This will install BookPub (globally) on your system. You will then be asked a series of questions to help setup your new project.
 
-**BookPub** is essentially an HTML/CSS/Javascript based book framework. All the different book formats are built off of this foundation. That said, we've attempted to help streamline the process by integrating common industry tools best-practices.
+    This is an example book to demonstrate how to use HTML/CSS/Javascript to publish a book. It's built off of the example [Boom! microformat here](https://alistapart.com/article/boom/). The answers to your `npx create-bookpub-project` will be used to fill in the title, author, etc.
 
-### 1. Creating Your New Book Project
+  * Test Drive - You can test drive your new project by changing into your new project `cd [your-project]` and creating a basic HTML format of your example book:
+
+      `bookpub build -t html`
+
+      This will build the HTML format of your new book.
+
+## Usage
 
-  * **Create your new BookPub project** - from the command-line (terminal), typeyour:
+We created **BookPub** in an effort to share an example of best-practices (or at least our opinion) for managing a manuscript-to-print pipeline. Rather than forcing people to follow rigid rules, we've attempted to provide a maximum of flexibility, while showing our example of the converntions that we use.
 
-    `bookpub new my-book` (where `my-book` is the name of your project)
+**BookPub** is essentially an HTML/CSS/Javascript based book framework. All the different book formats are built off of this foundation. That said, we've attempted to help streamline the process by integrating common industry tools and best-practices.
 
-    This will walk you through the creation of your new book project. You will be asked a series of questions and will generate our default book example, using your answers.
+### 1. Getting Started
 
-The project will have the following structure:
+Your new book project will have the following structure:
 
 ```plain
 my-book
@@ -107,7 +115,7 @@ my-book
 
 ### 2. Managing Your Book's Meta Data (book.config.yml)
 
-The `book.config.yml` is a [YAML File](https://www.cloudbees.com/blog/yaml-tutorial-everything-you-need-get-started) used to store your book's meta-data and configuration settings. You can use this file to store details about the book, like the title, isbn, author, lccn, etc. 
+The `book.config.yml` is a [YAML File](https://www.cloudbees.com/blog/yaml-tutorial-everything-you-need-get-started) used to store your book's meta-data and configuration settings. You can use this file to store details about the book, like the title, isbn, author, lccn, etc.
 
 All the data in `book.config.yml` is made available for you to use in the manuscript source.
 
@@ -141,36 +149,44 @@ The title of my book is My Book Title.
 
 ### 3. Working With Your Manuscript
 
-We have tried to give users as much flexibility as possible. That said, there are a few things to keep in mind:
+--> **One Manuscript To Rule Them All** <--
+
+**BookPub's** philosophy stems from the DRY (Don't Repeat Yourself) principle. As such, we want to always/only have one manuscript from which all the formats are built.
+
+You can arrange your manuscript in any way you like: One giant document, or a complicated breakout of different files and sections. We have tried to give users as much flexibility as possible.
+
+That said, there are a few things to keep in mind:
+
+--> **THREE SIMPLE RULES** <--
 
 1. All source code for your manuscript must be stored in the `manuscript/` folder.
 
 2. All files must end with .ejs (except for files in the theme folder)
 
-  * For a tutorial on using EJS, visit [the EJS Site](https://ejs.co/)
-
     * Our convention for naming files has been `[name].[filetype].ejs`.
+      * e.g. So, if we had an html file, it would be named `myname.html.ejs`
+    * For a tutorial on using EJS, visit [the EJS Site](https://ejs.co/)
 
-      * If we have an html file that we want to add, it will be named `myname.html.ejs`
-
-      * The only part of the name that is necessary is the `.ejs` extension. For the sake of clarity, we recommend describing the file-type in the middle.
+3. The entryfile (the beginning of your manuscript) must be specified in your book.config.yml (entryfile).
 
-3. The entryfile (the beginning of your manuscript) must be in your `manuscript/` folder.
+    * We recommend keeping the first file as `index.md.ejs`
 
-  * We recommend keeping the first file as `index.md.ejs`
+    * You can choose another name or location. But it must be specified in your `book.config.yml`
 
-  * You can choose another name or location. But it must be specified in your `book.config.yml`
+      For example, if you want your entryfile to be `myentryfile.md.ejs`, record it in your book.config.yml as:
 
-    For example, if you want your entryfile to be `myentryfile.md.ejs`, record it in your book.config.yml as:
+      ```yml
+      # book.config.yml
 
-    ```yml
-    # book.config.yml
+      # Let's set our entryfile
+      settings:
+        entryfile: myentryfile.md.ejs
 
-    # Let's set our entryfile
-    settings:
-      entryfile: myentryfile.md.ejs
+      ```
+4. Ok, so maybe we lied...another small rule/recommendation concerning your `theme` folder.
 
-    ```
+    * Keep in mind, during the build process, your `theme` folder will be copied over as-is.
+    * If you want to use SASS (.scss) to handle your css, you will need to keep the css as it is when your new book project is built. We will be changing this later, but for now, it's a requirement for SASS.
 
 ### 4. Building Your Book
 
@@ -188,39 +204,39 @@ The basic command for building a specific format (type) of your book is the foll
 
 2. The Print-PDF version of your book
 
-    (Remember, you need to install PrincXML to create a PDF format.)
-
   * To build a pdf typeset version of your book for print, type this command in your project's root directory:
 
     `bookpub build -t pdf`
 
     This will build your manuscript into a print-ready PDF version of your book in the `build/pdf/` folder.
 
-### 5. "Dev Mode" - A Development Workflow
+### 5. A Development Workflow
+
+--> **DEV MODE** <--
 
 We built the **BookPub** framework to make writing, designing, typesetting and formatting your book as streamlined and instantaneous as possible.
 
-With "Dev Mode", you can work in REAL TIME. Changes in your manuscript are rebuilt and reloaded in your browser in real time.
+With **DEV MODE**, you can work in REAL TIME. Changes in your manuscript are rebuilt and reloaded in your browser in real time.
 
-"Dev Mode" will launch a browser window that will display the newly built version of your book, which will be updated as changes are made to your manuscript.
+**DEV MODE** will launch a browser window that will display the newly built version of your book, which will be updated as changes are made to your manuscript.
 
 #### HTML "DEV" Mode
 
 To work on the HTML version of your book in "dev" mode, type:
 
-    `bookpub dev -t html`
+   `bookpub dev -t html`
 
 Now, as you edit your manuscript, the final HTML build will automatically be reloaded into your browser with the new updates.
 
 > Developer Note:
 >
 > 1. We are using Nodemon to watch for changes in your manuscript directory and build a new copy upon any change.
 >
->   * We have included your own nodemon.js file if you would like to make changes (but tread carefully)
+>     * We have included your own nodemon.js file if you would like to make changes (tread carefully)
 >
 > 2. We are using Webpack to serve any new builds to your browser and refresh when a new build is created.
 >
->   * We have included your own webpack.config.ejs if you would like to make changes (but tread carefully)
+>     * We have included your own webpack.config.ejs if you would like to make changes (tread carefully)
 
 #### PDF "DEV" MODE
 

cli.js

@@ -36,8 +36,8 @@ program.version(packageJson.version);
 
 program
     .command('build')
-    .option('-t, --type <type>', 'Specify the output type (html or pdf)', 'html')
-    .description('Build the output from the manuscript markdown files')
+    .option('-t, --type <type>', 'specify the output type (html or pdf)', 'html')
+    .description('build the output from the manuscript markdown files')
     .action(async (options) => {
         // Load the book.config.yml into the book object
         const book = await loadBookConfig();
@@ -58,8 +58,8 @@ program
 
 program
     .command('dev')
-    .option('-t, --type <type>', 'Specify the output type (html or pdf)', 'html')
-    .description('Run the development server with live-reloading')
+    .option('-t, --type <type>', 'specify the output type (html or pdf)', 'html')
+    .description('run the development server with live-reloading')
     .action(async (options) => {
         console.log(`\nRunning Nodemon and Webpack Server for ${options.type.toUpperCase()}...\n`);
         if (options.type === 'html') {
@@ -76,7 +76,7 @@ program
 
 program
     .command('new <projectName>')
-    .description('Create a new book project')
+    .description('create a new book project')
     .action(async (projectName) => {
         console.log(chalk.greenBright(`\nLet\'s create your new book project: ${chalk.yellowBright(projectName)}\n`));
 
@@ -87,7 +87,7 @@ program
 
 program
     .command('lint [fileName]')
-    .description('Lint EJS files in the manuscript folder.\n     \'bookpub lint\' - If no file name is specified, all EJS files will be linted.\n     \'bookpub lint [filename]\' - If a file name is specified, only that file will be linted.')
+    .description('lint EJS files in the manuscript folder.\n  \'bookpub lint\'         If no file name is specified, all EJS files will be linted.\n  \'bookpub lint [file]\'  If a file name is specified, only that file will be linted.\n')
     .action(async (fileName) => {
 
         try {
@@ -152,30 +152,23 @@ async function buildHtml(book, manuscriptDir, outputType, outputDir) {
 async function buildPdf(book, manuscriptDir, outputDir, outputType) {
     await buildHtml(book, manuscriptDir, outputDir, outputType);
 
+    const pdfOutDirRel = path.relative(process.cwd(), outputDir);
+    // Run the prince command-line tool
+    console.log(`  * Building your Print PDF to ${chalk.yellowBright(`/${pdfOutDirRel}/index.pdf`)}\n `);
+
     try {
-        const pdfOutDirRel = path.relative(process.cwd(), outputDir);
-        // Run the prince command-line tool
-        console.log(`  * Building your Print PDF to ${chalk.yellowBright(`/${pdfOutDirRel}/index.pdf`)}\n `);
         const prince = spawn('prince', ['build/pdf/index.html'], { stdio: 'inherit' });
+
         prince.on('error', (error) => {
-            console.error(`Error: ${error.message}`);
+            console.error(chalk.redBright('  Bummer. We couldn\'t build your pdf, because:'), chalk.magentaBright(error + '\nPlease make sure you have prince installed and available in your PATH.\n Visit https://www.princexml.com/doc/installing/ for more information.\n'));
         });
 
         return prince;
     } catch (error) {
-        console.error(chalk.redBright('  Bummer. We couldn\'t build your pdf, because:'), chalk.redBright(error + '\n'));
+        console.error(`Error: ${error.message}`);
     }
 }
 
-// Setup nodemon function to return as a Promise
-function runNodemonAsync(outputType) {
-    return new Promise(async (resolve, reject) => {
-        await runNodemon(outputType);
-        nodemon
-            .on('quit', resolve)
-            .on('error', reject);
-    });
-}
 
 // Run the webpack server using default settings
 async function runWebpackDevServerAsync(outputType) {
@@ -200,6 +193,16 @@ async function runWebpackDevServerAsync(outputType) {
     return server;
 }
 
+// Setup nodemon function to return as a Promise
+function runNodemonAsync(outputType) {
+    return new Promise(async (resolve, reject) => {
+        await runNodemon(outputType);
+        nodemon
+            .on('quit', resolve)
+            .on('error', reject);
+    });
+}
+
 async function runNodemon(outputType) {
     const env = { outputType, bookpubPath };
     const userNodemonConfig = await getNodemonConfig(env);