Fossil

Check-in [f1230cb3]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Automatically add HTML formatting to the on-line help when displaying in a web-page. (This is a work-in-progress. No everything displays correctly, yet.)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | formatted-online-help
Files: files | file ages | folders
SHA3-256: f1230cb3f3ace07b43e261c47a15441d86f0b1cb9ad69d5f62eeac2caeac289d
User & Date: drh 2020-06-24 21:50:24
Context
2020-06-25
00:16
Adjust help text to work better with the new formatter. (Leaf check-in: a8a60699 user: drh tags: formatted-online-help)
2020-06-24
21:50
Automatically add HTML formatting to the on-line help when displaying in a web-page. (This is a work-in-progress. No everything displays correctly, yet.) (check-in: f1230cb3 user: drh tags: formatted-online-help)
2020-06-23
12:52
Update the backoffice poller so that it invokes each backoffice at least once every hour - configurable using the --min command-line option. (check-in: e1d8cea2 user: drh tags: trunk)
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/dispatch.c.

214
215
216
217
218
219
220
221
222















































223
224
225
226













227
228

229




230
231






232
233
234


235
236




237




















238
239

240


241



















































242

243

244
245




























246
247
248
249
250
251
252
...
290
291
292
293
294
295
296
297
298
299
300

301

302
303
304




305

306
307
308
309
310
311
312
...
687
688
689
690
691
692
693
694
695
696
697
698
699
700

701
702
703
704
705
706
707




708
709
710
711
712
713
714


715
716
717
718
719
720
721
...
742
743
744
745
746
747
748

749
750
751
752
753
754
755
...
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
  int nPrefix = (int)strlen(zPrefix);
  for(i=FOSSIL_FIRST_CMD; i<MX_COMMAND; i++){
    if( strncmp(zPrefix, aCommand[i].zName, nPrefix)==0 ){
      blob_appendf(pList, " %s", aCommand[i].zName);
    }
  }
}

/*















































** Attempt to reformat plain-text help into HTML for display on a webpage.
**
** The HTML output is appended to Blob pHtml, which should already be
** initialized.













*/
static void help_to_html(const char *zHelp, Blob *pHtml){

  char *s;




  char *d;
  char *z;







  /* Transform "%fossil" into just "fossil" */
  z = s = d = mprintf("%s", zHelp);


  while( *s ){
    if( *s=='%' && strncmp(s, "%fossil", 7)==0 ){




      s++;




















    }else{
      *d++ = *s++;

    }


  }



















































  *d = 0;



  blob_appendf(pHtml, "<pre>\n%h\n</pre>\n", z);
  fossil_free(z);




























}

/*
** COMMAND: test-all-help
**
** Usage: %fossil test-all-help ?OPTIONS?
**
................................................................................
    fossil_print("-->\n");
    fossil_print("<!-- start_all_help -->\n");
  }else{
    fossil_print("---\n");
  }
  for(i=0; i<MX_COMMAND; i++){
    if( (aCommand[i].eCmdFlags & mask)==0 ) continue;
    fossil_print("# %s\n", aCommand[i].zName);
    if( useHtml ){
      Blob html;
      blob_zero(&html);

      help_to_html(aCommand[i].zHelp, &html);

      fossil_print("%s\n\n", blob_str(&html));
      blob_reset(&html);
    }else{




      fossil_print("%s\n\n", aCommand[i].zHelp);

    }
  }
  if( useHtml ){
    fossil_print("<!-- end_all_help -->\n");
  }else{
    fossil_print("---\n");
  }
................................................................................
@   --utc                   Display times using UTC
@   --vfs NAME              Cause SQLite to use the NAME VFS
;

/*
** COMMAND: help
**
** Usage: %fossil help TOPIC
**    or: %fossil TOPIC --help
**
** Display information on how to use TOPIC, which may be a command, webpage, or
** setting.  Webpage names begin with "/".  To display a list of available
** topics, use one of:
**

**    %fossil help                Show common commands
**    %fossil help -a|--all       Show both common and auxiliary commands
**    %fossil help -o|--options   Show command-line options common to all cmds
**    %fossil help -s|--setting   Show setting names
**    %fossil help -t|--test      Show test commands only
**    %fossil help -x|--aux       Show auxiliary commands only
**    %fossil help -w|--www       Show list of webpages




*/
void help_cmd(void){
  int rc;
  int isPage = 0;
  const char *z;
  const char *zCmdOrPage;
  const CmdOrPage *pCmd = 0;


  if( g.argc<3 ){
    z = g.argv[0];
    fossil_print(
      "Usage: %s help TOPIC\n"
      "Common commands:  (use \"%s help help\" for more options)\n",
      z, z);
    command_list(0, CMDFLAG_1ST_TIER);
................................................................................
    command_list(0, CMDFLAG_TEST);
    return;
  }
  else if( find_option("setting","s",0) ){
    command_list(0, CMDFLAG_SETTING);
    return;
  }

  isPage = ('/' == *g.argv[2]) ? 1 : 0;
  if(isPage){
    zCmdOrPage = "page";
  }else{
    zCmdOrPage = "command or setting";
  }
  rc = dispatch_name_search(g.argv[2], CMDFLAG_ANY|CMDFLAG_PREFIX, &pCmd);
................................................................................
  }
  if( pCmd->eCmdFlags & CMDFLAG_SETTING ){
    fossil_print("Setting: \"%s\"%s\n\n",
         pCmd->zName,
         (pCmd->eCmdFlags & CMDFLAG_VERSIONABLE)!=0 ? " (versionable)" : ""
    );
  }
  while( *z ){
    if( *z=='%' && strncmp(z, "%fossil", 7)==0 ){
      fossil_print("%s", g.argv[0]);
      z += 7;
    }else{
      putchar(*z);
      z++;
    }
  }
  putchar('\n');
}

/*
** Return a pointer to the setting information array.
**
** This routine provides access to the aSetting2[] array which is created
** by the mkindex utility program and included with <page_index.h>.









>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




>
>
>
>
>
>
>
>
>
>
>
>
>


>
|
>
>
>
>
|
<
>
>
>
>
>
>

<
<
>
>
|
<
>
>
>
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

<
>

>
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
>
|
>
|
<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







<


<
>

>
|


>
>
>
>
|
>







 







|
<


|
|

>
|
|
|
|
|
|
|
>
>
>
>







>
>







 







>







 







|
|
|
|
|
|
|
|
<
<







214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295

296
297
298
299
300
301
302


303
304
305

306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331

332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392

393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
...
465
466
467
468
469
470
471

472
473

474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
...
867
868
869
870
871
872
873
874

875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
...
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
...
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981


982
983
984
985
986
987
988
  int nPrefix = (int)strlen(zPrefix);
  for(i=FOSSIL_FIRST_CMD; i<MX_COMMAND; i++){
    if( strncmp(zPrefix, aCommand[i].zName, nPrefix)==0 ){
      blob_appendf(pList, " %s", aCommand[i].zName);
    }
  }
}

/*
** Return the index of the first non-space character that follows
** a span of two or more spaces.  Return 0 if there is not gap.
*/
static int hasGap(const char *z, int n){
  int i;
  for(i=3; i<n-1; i++){
    if( z[i]==' ' && z[i+1]!=' ' && z[i-1]==' ' ) return i+1;
  }
  return 0 ;
}

/*
** Append text to pOut, adding formatting markup.  Terms that
** have all lower-case letters are within <tt>..</tt>.  Terms
** that have all upper-case letters are within <i>..</i>.
*/
static void appendMixedFont(Blob *pOut, const char *z, int n){
  const char *zEnd = "";
  int i = 0;
  int j;
  while( i<n ){
    if( z[i]==' ' ){
      for(j=i+1; j<n && z[j]==' '; j++){}
      blob_append(pOut, z+i, j-i);
      i = j;
    }else{
      for(j=i; j<n && z[j]!=' ' && !fossil_isalpha(z[j]); j++){}
      if( j>=n || z[j]==' ' ){
        zEnd = "";
      }else{
        if( fossil_isupper(z[j]) ){
          blob_append(pOut, "<i>",3);
          zEnd = "</i>";
        }else{
          blob_append(pOut, "<tt>", 4);
          zEnd = "</tt>";
        }
      }
      while( j<n && z[j]!=' ' ){ j++; }
      blob_appendf(pOut, "%#h", j-i, z+i);
      if( zEnd[0] ) blob_append(pOut, zEnd, -1);
      i = j;
    }
  }
}

/*
** Attempt to reformat plain-text help into HTML for display on a webpage.
**
** The HTML output is appended to Blob pHtml, which should already be
** initialized.
**
** Formatting rules:
**
**   *  Bullet lists are indented from the surrounding text by
**      at least one space.  Each bullet begins with " * ".
**
**   *  Display lists are indented from the surrounding text.
**      Each tag begins with "-" or occur on a line that is
**      followed by two spaces and a non-space.  <dd> elements can begin
**      on the same line as long as they are separated by at least
**      two spaces.
**
**   *  Indented text is show verbatim (<pre>...</pre>)
*/
static void help_to_html(const char *zHelp, Blob *pHtml){
  int i;
  char c;
  int nIndent = 0;
  int wantP = 0;
  int wantBR = 0;
  int aIndent[10];
  const char *azEnd[10];

  int iLevel = 0;
  int isLI = 0;
  static const char *zEndDL = "</dl></blockquote>";
  static const char *zEndPRE = "</pre></blockquote>";
  static const char *zEndUL = "</ul>";
  static const char *zEndDD = "</dd>";



  aIndent[0] = 0;
  azEnd[0] = "";
  while( zHelp[0] ){

    i = 0;
    while( (c = zHelp[i])!=0
        && c!='\n'
        && (c!='%' || strncmp(zHelp+i,"%fossil",7)!=0)
    ){ i++; }
    if( c=='%' ){
      if( i ) blob_appendf(pHtml, "%#h", i, zHelp);
      zHelp += i + 1;
      i = 0;
      wantBR = 1;
      continue;
    }
    for(nIndent=0; nIndent<i && zHelp[nIndent]==' '; nIndent++){}
    if( nIndent==i ){
      if( c==0 ) break;
      blob_append(pHtml, "\n", 1);
      wantP = 1;
      wantBR = 0;
      zHelp += i+1;
      continue;
    }
    if( nIndent+2<i && zHelp[nIndent]=='*' && zHelp[nIndent+1]==' ' ){
      nIndent += 2;
      while( nIndent<i && zHelp[nIndent]==' '){ nIndent++; }
      isLI = 1;
    }else{

      isLI = 0;
    }
    while( iLevel>0 && aIndent[iLevel]>nIndent ){
      blob_append(pHtml, azEnd[iLevel--], -1);
    }
    if( nIndent>aIndent[iLevel] ){
      assert( iLevel<ArraySize(aIndent)-2 );
      if( isLI ){
        iLevel++;
        aIndent[iLevel] = nIndent;
        azEnd[iLevel] = zEndUL;
        blob_append(pHtml, "<ul>\n", 5);
      }else if( zHelp[nIndent]=='-' || hasGap(zHelp+nIndent,i-nIndent) ){
        iLevel++;
        aIndent[iLevel] = nIndent;
        azEnd[iLevel] = zEndDL;
        blob_append(pHtml, "<blockquote><dl>\n", -1);
      }else if( wantP && azEnd[iLevel]!=zEndDL ){
        iLevel++;
        aIndent[iLevel] = nIndent;
        azEnd[iLevel] = zEndPRE;
        blob_append(pHtml, "<blockquote><pre>", -1);
        wantP = 0;
      }
    }
    if( isLI ){
      blob_append(pHtml, "<li> ", 5);
    }
    if( wantP ){
      blob_append(pHtml, "<p> ", 4);
      wantP = 0;
    }
    if( azEnd[iLevel]==zEndDL ){
      int iDD;
      blob_append(pHtml, "<dt> ", 5);
      iDD = hasGap(zHelp+nIndent, i-nIndent);
      if( iDD ){
        int x;
        assert( iLevel<ArraySize(aIndent)-1 );
        iLevel++;
        aIndent[iLevel] = x = nIndent+iDD;
        azEnd[iLevel] = zEndDD;
        appendMixedFont(pHtml, zHelp+nIndent, iDD-2);
        blob_appendf(pHtml, "</dt><dd>%#h\n", x, zHelp+x);
      }else{
        appendMixedFont(pHtml, zHelp+nIndent, i-nIndent);
        blob_append(pHtml, "</dt>\n", 6);
      }
    }else if( wantBR ){
      appendMixedFont(pHtml, zHelp+nIndent, i-nIndent);
      blob_append(pHtml, "<br>\n", 5);
      wantBR = 0;
    }else{
      blob_appendf(pHtml, "%#h\n", i-nIndent, zHelp+nIndent);
    }
    zHelp += i+1;
    i = 0;
    if( c==0 ) break;
  }
  while( iLevel>0 ){
    blob_appendf(pHtml, "%s\n", azEnd[iLevel--]);

  }
}

/*
** Format help text for TTY display.
*/
static void help_to_text(const char *zHelp, Blob *pText){
  int i;
  char c;
  for(i=0; (c = zHelp[i])!=0; i++){
    if( c=='%' && strncmp(zHelp+i,"%fossil",7)==0 ){
      if( i>0 ) blob_append(pText, zHelp, i);
      blob_append(pText, "fossil", 6);
      zHelp += i+7;
      i = -1;
      continue;
    }
    if( c=='\n' && strncmp(zHelp+i+1,">  ",3)==0 ){
      if( i>0 ) blob_append(pText, zHelp, i-1);
      blob_append(pText, "  ", 6);
      zHelp += i+3;
      i = -1;
      continue;
    }
  }
  if( i>0 ){
    blob_append(pText, zHelp, i);
  }      
}

/*
** COMMAND: test-all-help
**
** Usage: %fossil test-all-help ?OPTIONS?
**
................................................................................
    fossil_print("-->\n");
    fossil_print("<!-- start_all_help -->\n");
  }else{
    fossil_print("---\n");
  }
  for(i=0; i<MX_COMMAND; i++){
    if( (aCommand[i].eCmdFlags & mask)==0 ) continue;

    if( useHtml ){
      Blob html;

      blob_init(&html, 0, 0);
      help_to_html(aCommand[i].zHelp, &html);
      fossil_print("<h1>%h</h1>\n", aCommand[i].zName);
      fossil_print("%s\n<hr>\n", blob_str(&html));
      blob_reset(&html);
    }else{
      Blob txt;
      blob_init(&txt, 0, 0);
      help_to_text(aCommand[i].zHelp, &txt);
      fossil_print("# %s\n", aCommand[i].zName);
      fossil_print("%s\n\n", blob_str(&txt));
      blob_reset(&txt);
    }
  }
  if( useHtml ){
    fossil_print("<!-- end_all_help -->\n");
  }else{
    fossil_print("---\n");
  }
................................................................................
@   --utc                   Display times using UTC
@   --vfs NAME              Cause SQLite to use the NAME VFS
;

/*
** COMMAND: help
**
** Usage: %fossil help [OPTIONS] [TOPIC]

**
** Display information on how to use TOPIC, which may be a command, webpage, or
** setting.  Webpage names begin with "/".  If TOPIC is omitted, a list of
** topics is returned.
**
** The following options can be used when TOPIC is omitted:
**
**    -a|--all          List both command and auxiliary commands
**    -o|--options      List command-line options common to all commands
**    -s|--setting      List setting names
**    -t|--test         List unsupported "test" commands
**    -x|--aux          List only auxiliary commands
**    -w|--www          List all web pages
**
** These options can be used when TOPIC is present:
**
**    -h|--html         Format output as HTML rather than plain text
*/
void help_cmd(void){
  int rc;
  int isPage = 0;
  const char *z;
  const char *zCmdOrPage;
  const CmdOrPage *pCmd = 0;
  int useHtml = 0;
  Blob txt;
  if( g.argc<3 ){
    z = g.argv[0];
    fossil_print(
      "Usage: %s help TOPIC\n"
      "Common commands:  (use \"%s help help\" for more options)\n",
      z, z);
    command_list(0, CMDFLAG_1ST_TIER);
................................................................................
    command_list(0, CMDFLAG_TEST);
    return;
  }
  else if( find_option("setting","s",0) ){
    command_list(0, CMDFLAG_SETTING);
    return;
  }
  useHtml = find_option("html","h",0)!=0;
  isPage = ('/' == *g.argv[2]) ? 1 : 0;
  if(isPage){
    zCmdOrPage = "page";
  }else{
    zCmdOrPage = "command or setting";
  }
  rc = dispatch_name_search(g.argv[2], CMDFLAG_ANY|CMDFLAG_PREFIX, &pCmd);
................................................................................
  }
  if( pCmd->eCmdFlags & CMDFLAG_SETTING ){
    fossil_print("Setting: \"%s\"%s\n\n",
         pCmd->zName,
         (pCmd->eCmdFlags & CMDFLAG_VERSIONABLE)!=0 ? " (versionable)" : ""
    );
  }
  blob_init(&txt, 0, 0);
  if( useHtml ){
    help_to_html(z, &txt);
  }else{
    help_to_text(z, &txt);
  }
  fossil_print("%s\n", blob_str(&txt));
  blob_reset(&txt);


}

/*
** Return a pointer to the setting information array.
**
** This routine provides access to the aSetting2[] array which is created
** by the mkindex utility program and included with <page_index.h>.